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).

Measured: the encoding argument

probe-triage2, 2026-10-04: AutoCAD 2022 at LISPSYS 0 (job 16923993438) answers (open f "w" "utf8") with "too many arguments" (nombre d'arguments trop important) – the third argument belongs to the Unicode engine (LISPSYS 1 / 2, 2021+). BricsCAD at LISPSYS 0 (V26 macOS job 16923993439, V25 Windows job 16923993442) opens the file.

probe-open-encoding, 2026-10-06 (MR !432: AutoCAD 2022 job 16967893842, BricsCAD V26 macOS job 16967893843, BricsCAD V25 Windows job 16968316289), writing "A" e-acute "B":

form AutoCAD 2022 (LISPSYS 0) BricsCAD V26 (macOS) BricsCAD V25 (Windows)
(open f "w") 3 bytes (cp1252) 4 bytes (UTF-8, no BOM) cp1252
(open f "w" "utf8") error: too many arguments accepted, no effect accepted, no effect
(open f "w" "utf8-bom") error: too many arguments accepted, no effect (no BOM) accepted, no effect
(open f "w" "cp1252") error: too many arguments error: bad argument type error: bad argument type
(open f "w,ccs=UTF-8") accepted, ignored accepted, ignored honoured (BOM)
(open f "w,ccs=UTF-16LE") accepted, ignored accepted, ignored honoured (BOM)

Appending on BricsCAD V25 Windows (probe-open-encoding, 2026-10-08, job 17027935338, ACADVER "25.0 BricsCAD"): "A" e-acute "B" written with the first mode, one e-acute appended with the second, file sizes after each and what a plain (open f "r") reads back:

write, then append sizes read back
"w,ccs=UTF-8", then "a,ccs=UTF-8" 7, 9 (65 195 169 66 195 169)
"w,ccs=UTF-16LE", then "a,ccs=UTF-16LE" 8, 10 (65 233 0 66 0 233 0)
"w,ccs=UTF-8", then a plain "a" 7, 8 (65 195 169 66 233)
"w" "utf8", then "a" "utf8" 3, 4 (65 233 66 233)

So an append with ,ccs= writes no second byte-order mark; a plain "a" appends cp1252 to the UTF-8 file.

The documented "utf8" / "utf8-bom" at AutoCAD LISPSYS 1 / 2 were measured by encoding experiment E1, 2026-10-06 (AutoCAD 2022 accoreconsole, LISPSYS set in every profile and the engine restarted per level, job 16980926802, MR !438, probe autolisp-front-end/tests/scenarios/entities/lispsys-bom-probe.lsp), writing "A" e-acute "B" with write-char and reading it back with read-char:

LISPSYS (open f "w") (open f "w" "utf8") (open f "w" "utf8-bom")
0 3 bytes, cp1252 error: too many arguments error: too many arguments
1, 2 3 bytes, cp1252 4 bytes, UTF-8, no BOM 7 bytes, BOM + UTF-8
LISPSYS (open f "r") (open f "r" "utf8")
0 cp1252 file: (65 233 66) error: too many arguments
1, 2 cp1252, UTF-8 and BOM + UTF-8 files all UTF-8: (65 233 66); BOM + UTF-8: (65279 65 233
  read (65 233 66) 66), the BOM is a character; cp1252: (65), the
    data ends at the byte that is not UTF-8

So LISPSYS changes the default READ (and LOAD), not the default WRITE: with no encoding argument AutoCAD 2022 writes cp1252 at every level, as Autodesk's page says ("the file is assumed to contain … (MBCS)").

Appending with the encoding argument (E1 again, 2026-10-08, job 16998925786): "A" e-acute "B" written with (open f "w" ENC), then one e-acute appended with (open f "a" ENC), file sizes after each:

LISPSYS "utf8" "utf8-bom"
0 error: too many arguments error: too many arguments
1, 2 4 then 6 (UTF-8 appended) 7 then 9 (UTF-8 appended, no second BOM)

An append to a file that does not exist yet was not measured.

clautolisp

Non-normative (pjb, 2026-10-06: "open third argument: lenient, but dialect warn when it's used in other dialects or strict"). clautolisp's open always honours its third argument ("utf8", "utf8-bom" and the broader clautolisp encoding names: "UTF-8", "cp1252", "ISO-8859-1", …) and the ",ccs=ENC" mode suffix, under every dialect; apart from the AutoCAD rules below, the file it writes does not depend on the dialect. Where the dialect's vendor would not do the same, it emits an out-of-dialect warning ([enc-foreign-dialect]; under strict [enc-extension-used]) naming what the vendor does, as measured above:

  • AutoCAD dialects before 2021, or on Windows at LISPSYS 0: any third argument (the vendor says "too many arguments"). At LISPSYS 1 / 2 (2021+) "utf8" / "utf8-bom" are silent (documented), any other name warns.
  • BricsCAD dialects: "utf8" / "utf8-bom" warn (accepted, no effect), any other name warns (bad argument type).
  • ",ccs=ENC": warns under the AutoCAD dialects and the non-Windows BricsCAD dialects (ignored there); silent under the Windows BricsCAD dialects for UTF-8 / UTF-16LE (honoured, measured), warns for any other name there (unmeasured). Honoured as BricsCAD V25 does: mode "w" writes the byte-order mark first; "a" on an existing file writes none; "a" creating the file writes it, as "w" (unmeasured).
  • strict warns for every form (not portable); clautolisp and lax are silent.

The warning is printed at each call, through the encoding-diagnostic channel (pragma-suppressible; (setq *AUTOLISP-WARN-OUT-OF-DIALECT* nil) silences it); clal-lint-encoding-extensions reports the same forms statically.

AutoCAD dialects: the encoding AutoCAD uses (clautolisp 2.2.222, autocad-open-encoding-lispsys-divergence; clautolisp implementation deviation – not part of the normative specification above). Under every AutoCAD dialect (any version, any platform) clautolisp reproduces the E1 measurement above:

  • (open f "w") / (open f "a") with no encoding argument and no ,ccs= suffix write windows-1252 at every LISPSYS level – LISPSYS (read at launch into *AUTOLISP-FILE-ENCODING*) governs load and the default read only. Two clautolisp knobs still override it: the file situation (-Efile-write, *AUTOLISP-FILE-WRITE-ENCODING*) and an explicit -Esource / -e (then the write follows *AUTOLISP-FILE-ENCODING* as in the other dialects). A runtime (setq *AUTOLISP-FILE-ENCODING* ...) does not change the default write under these dialects; set *AUTOLISP-FILE-WRITE-ENCODING* for that.
  • (open f "w" "utf8-bom") writes the BOM (EF BB BF) before the UTF-8 text; "utf8" writes UTF-8 without one. Only mode "w" writes the BOM: "a" appends none, which matches AutoCAD on a file that already exists (measured above: no second BOM); "a" creating a new file was not measured.
  • (open f "r") with no encoding argument, when the default read encoding is UTF-8 (LISPSYS 1 / 2): a UTF-8 BOM is skipped, a well-formed UTF-8 file is decoded as UTF-8, any other file as windows-1252 – the rule AutoCAD's load follows too. At LISPSYS 0 (windows-1252) the read is plain windows-1252 (only a cp1252 file was measured there; no BOM skip).
  • (open f "r" "utf8") is strict: a BOM is returned as the character U+FEFF (65279), and the data ends – read-char / read-line return nil – at the first byte that does not continue well-formed UTF-8. "utf8-bom" for reading was not measured and decodes as before (UTF-8, the BOM returned as a character, no truncation).

At LISPSYS 0 AutoCAD refuses the third argument altogether; clautolisp still honours it as at LISPSYS 1 / 2 (and warns, as above). The BricsCAD, strict, clautolisp and lax dialects keep their behaviour: no BOM for "utf8-bom" (BricsCAD was measured to write none), the default read and write follow *AUTOLISP-FILE-ENCODING* / the dialect default, and "utf8" decodes with the host's UTF-8 decoder.

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.