Function Entry: OPEN

← Prev | ↑ Chapter | Next → | Index | Symbols

Function Entry: OPEN

Name

open

Class

Function

Syntax

(open filename mode [encoding])

Arguments and Values

  • filename: string
  • mode: string designating read, write, or append
  • encoding: optional encoding designator; see File encoding below

Description

Opens a file and returns a file descriptor.

File encoding

The optional third argument is version-qualified: pre-2021 open has no encoding argument at all. It was introduced by AutoCAD 2021 and is supported in BricsCAD V21 and higher.

The values the vendors document are:

value meaning
"utf8" UTF-8, no byte-order mark
"utf8-bom" UTF-8 preceded by a BOM
"utf16-bom" UTF-16 preceded by a BOM

With no encoding argument the file is read and written in the host's system codepage (SYSCODEPAGE).

The reason the list stops there is stated by Bricsys and is worth repeating, because it is the whole difficulty: "UTF-8 without BOM can not be distinguished from normal ANSI." There is no byte sequence that tells the two apart, so a file written as UTF-8 without a mark is indistinguishable from one written in the host codepage — and on a host whose codepage is not cp1252 (macOS, where SYSCODEPAGE is MACROMAN) it is decoded wrongly, silently. This is the mechanism behind the observed macOS mis-decoding, not a separate bug.

Modes "r", "w" and "a" are text; "rb", "wb" and "ab" are binary, where no decoding applies and the encoding argument is meaningless.

Consistency required of any implementation

Whatever the file encoding, a decoded non-ASCII character must satisfy 

(= (chr N) <the same character decoded from a file>)

— one canonical internal representation per character, however it entered the image. BricsCAD's native chr diverges from this today (see cad-chr-vs-loaded-encoding.issue for the measurements); clautolisp satisfies it. Stating the rule here is what gives alfe a contract to honour when it hands sources to a CAD host: transcode to UTF-8 with a BOM, which is the one form every post-2021 engine reads unambiguously.

Return Values

Returns a FILE descriptor or nil on failure, depending on host behavior and context.

Side Effects

Creates or opens an external file channel.

Affected By

  • path-resolution rules
  • trusted-path rules
  • encoding support

Exceptional Situations

Errors are reported for invalid paths, modes, or inaccessible files.

Examples

  • (open "foo.txt" "r")

Compatibility

  • older Autodesk forms lacked explicit encoding: the argument is an AutoCAD 2021 feature, mirrored by BricsCAD from V21
  • BricsCAD documents richer text mode handling

Source Notes

Notes

clautolisp should decouple path semantics from native OS via environment profiles.

In clautolisp, open resolves a relative name through the support search path (an existing file is found on the path; a new name falls back to the current directory, so write semantics are unchanged). That current directory is the process working directory at launch — matching BricsCAD/AutoCAD, which resolve a relative name against the current directory — and user code may query or change it with vl-getcurrentdir / vl-setcurrentdir. This holds identically whether clautolisp runs standalone or in-process behind alfe --clautolisp (the in-process backend re-anchors to the live cwd at start-up; see issues/closed/cad-open-relative-path-not-resolved-vs-cwd.issue). open is also gated by the trust model for files whose extension is in the gated set: at SECURELOAD 2 an untrusted gated file is blocked (ERRNO + a :open-untrusted-file error), at 1 it warns and proceeds; ordinary data files are never gated. Autodesk does not gate open — this is a clautolisp extension (1.2.18 / 1.2.20). See Normative Rules: Secure File Loading and Trust Model (this chapter).

Availability

  • AutoCAD 2026: documented (per Autodesk reference page).
  • BricsCAD V26: presumed compatible (no contradicting page found).
  • Status: AutoCAD documented; BricsCAD presumed-both pending Phase 4 verification.

See Also

  • BricsCAD V26 extends open with encoding selectors of the form "r,ccs=UNICODE", "r,ccs=UTF-8", "r,ccs=UTF-16LE", "w,ccs=UTF-8", "w,ccs=UTF-16LE". AutoCAD does not accept these; AutoCAD's Unicode story is governed by the LISPSYS system variable instead.
  • Divergence documented in vendor-inventory-2026.org §10 item 2.