Function Entry: OPEN
← Prev | ↑ Chapter | Next → | Index | Symbols
Function Entry: OPEN
Name
open
Class
Function
Syntax
(open filename mode [encoding])
Arguments and Values
filename: stringmode: string designating read, write, or appendencoding: 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
- Bricsys, BricsCAD Developer Reference V25,
open— https://developer.bricsys.com/bricscad/help/en_US/V25/DevRef/source/open.htm (the encoding values and the "cannot be distinguished from normal ANSI" statement are verbatim from that page). - The AutoCAD 2021 Unicode changes are the same feature under
LISPSYS; the two vendors agree on the argument.
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 forUTF-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).strictwarns for every form (not portable);clautolispandlaxare 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*) governsloadand the default read only. Two clautolisp knobs still override it: thefilesituation (-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'sloadfollows 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-linereturnnil– 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
openwith 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 theLISPSYSsystem variable instead. - Divergence documented in
vendor-inventory-2026.org§10 item 2.
Source Notes
- [open (AutoLISP), current](https://help.autodesk.com/cloudhelp/2026/PLK/AutoCAD-LT-AutoLISP-Reference/files/GUID-089A323F-21FF-4337-99A9-375758E23BA4.htm)
- [open (AutoLISP), earlier](https://help.autodesk.com/cloudhelp/2015/ENU/AutoCAD-AutoLISP/files/GUID-089A323F-21FF-4337-99A9-375758E23BA4.htm)
- [read + write text files (BricsCAD)](https://developer.bricsys.com/bricscad/help/en_US/V25/DevRef/source/readwritetextfiles.htm)
- Status: documented with version drift.