marcuskammer/cl-sites
1
0
Fork 0
Code Activity
cl-sites/novaspec.org/cl/f_open.html

1326 lines
27 KiB
HTML
Raw Normal View History

Add novaspec
2025-02-05 18:52:26 +01:00
<!DOCTYPE HTML>
<HTML LANG="en-us"
><HEAD
><TITLE
>open | Common Lisp Nova Spec</TITLE
><META CHARSET="US-ASCII"
><LINK REL="canonical" HREF="f_open.html"
><LINK REL="next" HREF="f_stream-external-format.html" TYPE="text/html" TITLE="stream-external-format"
><LINK REL="prev" HREF="f_file-string-length.html" TYPE="text/html" TITLE="file-string-length"
><LINK REL="up" HREF="21_2_Streams_Dictionary.html" TYPE="text/html" TITLE="21.2 Streams Dictionary"
><LINK REL="start" HREF="index.html" TYPE="text/html" TITLE="Common Lisp Nova Spec"
><META NAME="VIEWPORT" CONTENT="width=device-width, initial-scale=1.0"
><LINK REL="STYLESHEET" HREF="dpans.css%3F3909942064.css"
><SCRIPT SRC="dpans.js%3F3909942064"
></SCRIPT
><SCRIPT SRC="apropos.js%3F3909942064"
></SCRIPT
></HEAD
><BODY
><DIV
><DIV CLASS="topnav"
><DIV CLASS="breadcrumb"
><SPAN CLASS="breadcrumb-item"
><A HREF="index.html"
>Common Lisp Nova Spec</A
></SPAN
> <SPAN CLASS="breadcrumb-item"
>&#8594; <A HREF="21_Streams.html"
>21. Streams</A
></SPAN
> <SPAN CLASS="breadcrumb-item"
>&#8594; <A HREF="21_2_Streams_Dictionary.html"
>21.2 Streams Dictionary</A
></SPAN
> <SPAN CLASS="breadcrumb-item"
>&#8594; <A HREF="f_open.html"
>open</A
></SPAN
></DIV
><DIV CLASS="apropos"
><DIV CLASS="apropos-io"
><A HREF="f_file-string-length.html" CLASS="prev"
>&#8592;</A
><SPAN ID="apropos-label"
>Apropos </SPAN
><INPUT ID="apropos" AUTOFOCUS="AUTOFOCUS" PLACEHOLDER="Type here to search" ONINPUT="aproposInput(this);" ONKEYUP="aproposKeyup(event);" ONCHANGE="aproposChange(this);" ONFOCUS="aproposFocus(this);" ONFOCUSOUT="aproposFocusout(this);"
><A HREF="f_stream-external-format.html" CLASS="next"
>&#8594;</A
></DIV
><DIV ID="apropos-res"
></DIV
></DIV
></DIV
><DIV CLASS="matter"
><DIV CLASS="com"
><DIV CLASS="begincom"
><HR
><TABLE WIDTH="100%" CELLSPACING="0" CELLPADDING="0"
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="100%" CLASS="name"
><SPAN CLASS="idx" DATA-KIND="idxref" DATA-TERM="open"
></SPAN
><B
>open</B
></TD
><TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="0" NOWRAP="NOWRAP" CLASS="ftype"
><I
>Function</I
></TD
></TR
></TABLE
><HR
></DIV
><UL CLASS="subtoc"
></UL
><DL
><DT
><B
>Syntax</B
></DT
><DD
><TABLE CELLPADDING="0" CELLSPACING="0"
><TR
><TD VALIGN="BASELINE" ALIGN="LEFT" NOWRAP="NOWRAP"
><B
>open</B
><SPAN CLASS="cmssi"
>&#160;</SPAN
><SPAN CLASS="cmssi"
>filespec</SPAN
><SPAN CLASS="cmtt"
>&#160;</SPAN
><SPAN CLASS="cmtt"
>&amp;key</SPAN
><SPAN CLASS="cmssi"
>&#160;</SPAN
></TD
><TD VALIGN="BASELINE" ALIGN="LEFT"
><SPAN CLASS="cmssi"
>direction</SPAN
> <SPAN CLASS="cmssi"
>element-type</SPAN
><BR
><SPAN CLASS="cmssi"
>if-exists</SPAN
> <SPAN CLASS="cmssi"
>if-does-not-exist</SPAN
> <SPAN CLASS="cmssi"
>external-format</SPAN
></TD
></TR
></TABLE
><DIV
><SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> <SPAN CLASS="cmssi"
>stream</SPAN
></DIV
></DD
><DT
><B
>Arguments and Values</B
></DT
><DD
><P CLASS="j"
><VAR CLASS="param"
>filespec</VAR
> &#8212; a <A HREF="26_1_Glossary.html#pathname_designator"
><EM CLASS="term"
>pathname designator</EM
></A
>. </P
><P CLASS="j"
><VAR CLASS="param"
>direction</VAR
> &#8212; one of <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:input</SPAN
></SPAN
>, <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:output</SPAN
></SPAN
>, <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:io</SPAN
></SPAN
>, or <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:probe</SPAN
></SPAN
>. The default is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:input</SPAN
></SPAN
>. </P
><P CLASS="j"
><VAR CLASS="param"
>element-type</VAR
> &#8212; a <A HREF="26_1_Glossary.html#type_specifier"
><EM CLASS="term"
>type specifier</EM
></A
> for <A HREF="26_1_Glossary.html#recognizable_subtype"
><EM CLASS="term"
>recognizable subtype</EM
></A
> of <A HREF="t_character.html" CLASS="typeref"
><B
>character</B
></A
>; or a <A HREF="26_1_Glossary.html#type_specifier"
><EM CLASS="term"
>type specifier</EM
></A
> for a <A HREF="26_1_Glossary.html#finite"
><EM CLASS="term"
>finite</EM
></A
> <A HREF="26_1_Glossary.html#recognizable_subtype"
><EM CLASS="term"
>recognizable subtype</EM
></A
> of <A HREF="26_1_Glossary.html#integer"
><EM CLASS="term"
>integer</EM
></A
>; or one of the <A HREF="26_1_Glossary.html#symbol"
><EM CLASS="term"
>symbols</EM
></A
> <A HREF="t_signed-byte.html" CLASS="misc"
><B
>signed-byte</B
></A
>, <A HREF="t_unsigned-byte.html" CLASS="misc"
><B
>unsigned-byte</B
></A
>, or <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:default</SPAN
></SPAN
>. The default is <A HREF="t_character.html" CLASS="typeref"
><B
>character</B
></A
>. </P
><P CLASS="j"
><VAR CLASS="param"
>if-exists</VAR
> &#8212; one of <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:error</SPAN
></SPAN
>, <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:new-version</SPAN
></SPAN
>, <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:rename</SPAN
></SPAN
>, <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:rename-and-delete</SPAN
></SPAN
>, <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:overwrite</SPAN
></SPAN
>, <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:append</SPAN
></SPAN
>, <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:supersede</SPAN
></SPAN
>, or <SPAN CLASS="misc"
><B
>nil</B
></SPAN
>. The default is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:new-version</SPAN
></SPAN
> if the version component of <VAR CLASS="param"
>filespec</VAR
> is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:newest</SPAN
></SPAN
>, or <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:error</SPAN
></SPAN
> otherwise. </P
><P CLASS="j"
><VAR CLASS="param"
>if-does-not-exist</VAR
> &#8212; one of <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:error</SPAN
></SPAN
>, <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:create</SPAN
></SPAN
>, or <SPAN CLASS="misc"
><B
>nil</B
></SPAN
>. The default is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:error</SPAN
></SPAN
> if <VAR CLASS="param"
>direction</VAR
> is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:input</SPAN
></SPAN
> or <VAR CLASS="param"
>if-exists</VAR
> is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:overwrite</SPAN
></SPAN
> or <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:append</SPAN
></SPAN
>; <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:create</SPAN
></SPAN
> if <VAR CLASS="param"
>direction</VAR
> is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:output</SPAN
></SPAN
> or <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:io</SPAN
></SPAN
>, and <VAR CLASS="param"
>if-exists</VAR
> is neither <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:overwrite</SPAN
></SPAN
> nor <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:append</SPAN
></SPAN
>; or <SPAN CLASS="misc"
><B
>nil</B
></SPAN
> when <VAR CLASS="param"
>direction</VAR
> is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:probe</SPAN
></SPAN
>. </P
><P CLASS="j"
><VAR CLASS="param"
>external-format</VAR
> &#8212; an <A HREF="26_1_Glossary.html#external_file_format_designator"
><EM CLASS="term"
>external file format designator</EM
></A
>. The default is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:default</SPAN
></SPAN
>. </P
><P CLASS="j"
><VAR CLASS="param"
>stream</VAR
> &#8212; a <A HREF="26_1_Glossary.html#file_stream"
><EM CLASS="term"
>file stream</EM
></A
> or <SPAN CLASS="misc"
><B
>nil</B
></SPAN
>.</P
></DD
><DT
><B
>Description</B
></DT
><DD
><P CLASS="j"
><A HREF="f_open.html" CLASS="funref"
><B
>open</B
></A
> creates, opens, and returns a <A HREF="26_1_Glossary.html#file_stream"
><EM CLASS="term"
>file stream</EM
></A
> that is connected to the file specified by <VAR CLASS="param"
>filespec</VAR
>. <VAR CLASS="param"
>Filespec</VAR
> is the name of the file to be opened. If the <VAR CLASS="param"
>filespec</VAR
> <A HREF="26_1_Glossary.html#designator"
><EM CLASS="term"
>designator</EM
></A
> is a <A HREF="26_1_Glossary.html#stream"
><EM CLASS="term"
>stream</EM
></A
>, that <A HREF="26_1_Glossary.html#stream"
><EM CLASS="term"
>stream</EM
></A
> is not closed first or otherwise affected. </P
><P CLASS="j"
>The keyword arguments to <A HREF="f_open.html" CLASS="funref"
><B
>open</B
></A
> specify the characteristics of the <A HREF="26_1_Glossary.html#file_stream"
><EM CLASS="term"
>file stream</EM
></A
> that is returned, and how to handle errors. </P
><P CLASS="j"
>If <VAR CLASS="param"
>direction</VAR
> is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:input</SPAN
></SPAN
> or <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:probe</SPAN
></SPAN
>, or if <VAR CLASS="param"
>if-exists</VAR
> is not <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:new-version</SPAN
></SPAN
> and the version component of the <VAR CLASS="param"
>filespec</VAR
> is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:newest</SPAN
></SPAN
>, then the file opened is that file already existing in the file system that has a version greater than that of any other file in the file system whose other pathname components are the same as those of <VAR CLASS="param"
>filespec</VAR
>. </P
><P CLASS="j"
>An implementation is required to recognize all of the <A HREF="f_open.html" CLASS="funref"
><B
>open</B
></A
> keyword options and to do something reasonable in the context of the host operating system. For example, if a file system does not support distinct file versions and does not distinguish the notions of deletion and expunging, <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:new-version</SPAN
></SPAN
> might be treated the same as <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:rename</SPAN
></SPAN
> or <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:supersede</SPAN
></SPAN
>, and <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:rename-and-delete</SPAN
></SPAN
> might be treated the same as <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:supersede</SPAN
></SPAN
>.</P
><DL
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:direction</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>These are the possible values for <VAR CLASS="param"
>direction</VAR
>, and how they affect the nature of the <A HREF="26_1_Glossary.html#stream"
><EM CLASS="term"
>stream</EM
></A
> that is created:</P
><DL
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:input</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>Causes the creation of an <A HREF="26_1_Glossary.html#input"
><EM CLASS="term"
>input</EM
></A
> <A HREF="26_1_Glossary.html#file_stream"
><EM CLASS="term"
>file stream</EM
></A
>.</P
></DD
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:output</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>Causes the creation of an <A HREF="26_1_Glossary.html#output"
><EM CLASS="term"
>output</EM
></A
> <A HREF="26_1_Glossary.html#file_stream"
><EM CLASS="term"
>file stream</EM
></A
>.</P
></DD
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:io</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>Causes the creation of a <A HREF="26_1_Glossary.html#bidirectional"
><EM CLASS="term"
>bidirectional</EM
></A
> <A HREF="26_1_Glossary.html#file_stream"
><EM CLASS="term"
>file stream</EM
></A
>.</P
></DD
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:probe</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>Causes the creation of a &#8220;no-directional&#8221; <A HREF="26_1_Glossary.html#file_stream"
><EM CLASS="term"
>file stream</EM
></A
>; in effect, the <A HREF="26_1_Glossary.html#file_stream"
><EM CLASS="term"
>file stream</EM
></A
> is created and then closed prior to being returned by <A HREF="f_open.html" CLASS="funref"
><B
>open</B
></A
>.</P
></DD
></DL
></DD
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:element-type</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>The <VAR CLASS="param"
>element-type</VAR
> specifies the unit of transaction for the <A HREF="26_1_Glossary.html#file_stream"
><EM CLASS="term"
>file stream</EM
></A
>. If it is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:default</SPAN
></SPAN
>, the unit is determined by <A HREF="26_1_Glossary.html#file_system"
><EM CLASS="term"
>file system</EM
></A
>, possibly based on the <A HREF="26_1_Glossary.html#file"
><EM CLASS="term"
>file</EM
></A
>.</P
></DD
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:if-exists</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
><VAR CLASS="param"
>if-exists</VAR
> specifies the action to be taken if <VAR CLASS="param"
>direction</VAR
> is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:output</SPAN
></SPAN
> or <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:io</SPAN
></SPAN
> and a file of the name <VAR CLASS="param"
>filespec</VAR
> already exists. If <VAR CLASS="param"
>direction</VAR
> is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:input</SPAN
></SPAN
>, not supplied, or <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:probe</SPAN
></SPAN
>, <VAR CLASS="param"
>if-exists</VAR
> is ignored. These are the results of <A HREF="f_open.html" CLASS="funref"
><B
>open</B
></A
> as modified by <VAR CLASS="param"
>if-exists</VAR
>:</P
><DL
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:error</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>An error of <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> <A HREF="t_file-error.html" CLASS="typeref"
><B
>file-error</B
></A
> is signaled.</P
></DD
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:new-version</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>A new file is created with a larger version number.</P
></DD
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:rename</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>The existing file is renamed to some other name and then a new file is created.</P
></DD
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:rename-and-delete</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>The existing file is renamed to some other name, then it is deleted but not expunged, and then a new file is created.</P
></DD
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:overwrite</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>Output operations on the <A HREF="26_1_Glossary.html#stream"
><EM CLASS="term"
>stream</EM
></A
> destructively modify the existing file. If <VAR CLASS="param"
>direction</VAR
> is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:io</SPAN
></SPAN
> the file is opened in a bidirectional mode that allows both reading and writing. The file pointer is initially positioned at the beginning of the file; however, the file is not truncated back to length zero when it is opened.</P
></DD
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:append</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>Output operations on the <A HREF="26_1_Glossary.html#stream"
><EM CLASS="term"
>stream</EM
></A
> destructively modify the existing file. The file pointer is initially positioned at the end of the file. </P
><P CLASS="j"
>If <VAR CLASS="param"
>direction</VAR
> is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:io</SPAN
></SPAN
>, the file is opened in a bidirectional mode that allows both reading and writing.</P
></DD
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:supersede</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>The existing file is superseded; that is, a new file with the same name as the old one is created. If possible, the implementation should not destroy the old file until the new <A HREF="26_1_Glossary.html#stream"
><EM CLASS="term"
>stream</EM
></A
> is closed.</P
></DD
><DT
><SPAN CLASS="misc"
><B
>nil</B
></SPAN
></DT
><DD
><P CLASS="j"
>No file or <A HREF="26_1_Glossary.html#stream"
><EM CLASS="term"
>stream</EM
></A
> is created; instead, <SPAN CLASS="misc"
><B
>nil</B
></SPAN
> is returned to indicate failure.</P
></DD
></DL
></DD
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:if-does-not-exist</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
><VAR CLASS="param"
>if-does-not-exist</VAR
> specifies the action to be taken if a file of name <VAR CLASS="param"
>filespec</VAR
> does not already exist. These are the results of <A HREF="f_open.html" CLASS="funref"
><B
>open</B
></A
> as modified by <VAR CLASS="param"
>if-does-not-exist</VAR
>:</P
><DL
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:error</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>An error of <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> <A HREF="t_file-error.html" CLASS="typeref"
><B
>file-error</B
></A
> is signaled.</P
></DD
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:create</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>An empty file is created. Processing continues as if the file had already existed but no processing as directed by <VAR CLASS="param"
>if-exists</VAR
> is performed.</P
></DD
><DT
><SPAN CLASS="misc"
><B
>nil</B
></SPAN
></DT
><DD
><P CLASS="j"
>No file or <A HREF="26_1_Glossary.html#stream"
><EM CLASS="term"
>stream</EM
></A
> is created; instead, <SPAN CLASS="misc"
><B
>nil</B
></SPAN
> is returned to indicate failure.</P
></DD
></DL
></DD
><DT
><SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:external-format</SPAN
></SPAN
></DT
><DD
><P CLASS="j"
>This option selects an <A HREF="26_1_Glossary.html#external_file_format"
><EM CLASS="term"
>external file format</EM
></A
> for the <A HREF="26_1_Glossary.html#file"
><EM CLASS="term"
>file</EM
></A
>: The only <A HREF="26_1_Glossary.html#standardized"
><EM CLASS="term"
>standardized</EM
></A
> value for this option is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:default</SPAN
></SPAN
>, although <A HREF="26_1_Glossary.html#implementation"
><EM CLASS="term"
>implementations</EM
></A
> are permitted to define additional <A HREF="26_1_Glossary.html#external_file_format"
><EM CLASS="term"
>external file formats</EM
></A
> and <A HREF="26_1_Glossary.html#implementation-dependent"
><EM CLASS="term"
>implementation-dependent</EM
></A
> values returned by <A HREF="f_stream-external-format.html" CLASS="funref"
><B
>stream-external-format</B
></A
> can also be used by <A HREF="26_1_Glossary.html#conforming_program"
><EM CLASS="term"
>conforming programs</EM
></A
>. </P
><P CLASS="j"
>The <VAR CLASS="param"
>external-format</VAR
> is meaningful for any kind of <A HREF="26_1_Glossary.html#file_stream"
><EM CLASS="term"
>file stream</EM
></A
> whose <A HREF="26_1_Glossary.html#element_type"
><EM CLASS="term"
>element type</EM
></A
> is a <A HREF="26_1_Glossary.html#subtype"
><EM CLASS="term"
>subtype</EM
></A
> of <A HREF="26_1_Glossary.html#character"
><EM CLASS="term"
>character</EM
></A
>. This option is ignored for <A HREF="26_1_Glossary.html#stream"
><EM CLASS="term"
>streams</EM
></A
> for which it is not meaningful; however, <A HREF="26_1_Glossary.html#implementation"
><EM CLASS="term"
>implementations</EM
></A
> may define other <A HREF="26_1_Glossary.html#element_type"
><EM CLASS="term"
>element types</EM
></A
> for which it is meaningful. The consequences are unspecified if a <A HREF="26_1_Glossary.html#character"
><EM CLASS="term"
>character</EM
></A
> is written that cannot be represented by the given <A HREF="26_1_Glossary.html#external_file_format"
><EM CLASS="term"
>external file format</EM
></A
>.</P
></DD
></DL
><P CLASS="j"
>When a file is opened, a <A HREF="26_1_Glossary.html#file_stream"
><EM CLASS="term"
>file stream</EM
></A
> is constructed to serve as the file system&#8217;s ambassador to the Lisp environment; operations on the <A HREF="26_1_Glossary.html#file_stream"
><EM CLASS="term"
>file stream</EM
></A
> are reflected by operations on the file in the file system. </P
><P CLASS="j"
>A file can be deleted, renamed, or destructively modified by <A HREF="f_open.html" CLASS="funref"
><B
>open</B
></A
>. </P
><P CLASS="j"
>For information about opening relative pathnames, see <A HREF="19_2_Pathnames.html#sec_19_2_3" CLASS="secref"
><SPAN CLASS="cmr"
>Section</SPAN
> <SPAN CLASS="cmr"
>19.2.3</SPAN
> <SPAN CLASS="cmr"
>(Merging</SPAN
> <SPAN CLASS="cmr"
>Pathnames)</SPAN
></A
>.</P
></DD
><DT
><B
>Examples</B
></DT
><DD
><PRE CLASS="screen"
> (open <I CLASS="i"
><I
>filespec</I
></I
> :direction :probe) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> #&lt;Closed Probe File Stream...&gt;
(setq q (merge-pathnames (user-homedir-pathname) "test"))
<SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> #&lt;PATHNAME :HOST NIL :DEVICE <I CLASS="i"
><I
>device-name</I
></I
> :DIRECTORY <I CLASS="i"
><I
>directory-name</I
></I
>
:NAME "test" :TYPE NIL :VERSION :NEWEST&gt;
(open <I CLASS="i"
><I
>filespec</I
></I
> :if-does-not-exist :create) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> #&lt;Input File Stream...&gt;
(setq s (open <I CLASS="i"
><I
>filespec</I
></I
> :direction :probe)) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> #&lt;Closed Probe File Stream...&gt;
(truename s) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> #&lt;PATHNAME :HOST NIL :DEVICE <I CLASS="i"
><I
>device-name</I
></I
> :DIRECTORY
<I CLASS="i"
><I
>directory-name</I
></I
> :NAME <I CLASS="i"
><I
>filespec</I
></I
> :TYPE <I CLASS="i"
><I
>extension</I
></I
> :VERSION 1&gt;
(open s :direction :output :if-exists nil) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> NIL</PRE
></DD
><DT
><B
>Affected By</B
></DT
><DD
><P CLASS="j"
>The nature and state of the host computer&#8217;s <A HREF="26_1_Glossary.html#file_system"
><EM CLASS="term"
>file system</EM
></A
>.</P
></DD
><DT
><B
>Exceptional Situations</B
></DT
><DD
><P CLASS="j"
>If <VAR CLASS="param"
>if-exists</VAR
> is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:error</SPAN
></SPAN
>, (subject to the constraints on the meaning of <VAR CLASS="param"
>if-exists</VAR
> listed above), an error of <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> <A HREF="t_file-error.html" CLASS="typeref"
><B
>file-error</B
></A
> is signaled. </P
><P CLASS="j"
>If <VAR CLASS="param"
>if-does-not-exist</VAR
> is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:error</SPAN
></SPAN
> (subject to the constraints on the meaning of <VAR CLASS="param"
>if-does-not-exist</VAR
> listed above), an error of <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> <A HREF="t_file-error.html" CLASS="typeref"
><B
>file-error</B
></A
> is signaled. </P
><P CLASS="j"
>If it is impossible for an implementation to handle some option in a manner close to what is specified here, an error of <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> <A HREF="t_error.html" CLASS="typeref"
><B
>error</B
></A
> might be signaled. </P
><P CLASS="j"
>An error of <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> <A HREF="t_file-error.html" CLASS="typeref"
><B
>file-error</B
></A
> is signaled if <SPAN CLASS="cmtt"
>(wild-pathname-p</SPAN
> <VAR CLASS="param"
>filespec</VAR
><SPAN CLASS="cmtt"
>)</SPAN
> returns true. </P
><P CLASS="j"
>An error of <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> <A HREF="t_error.html" CLASS="typeref"
><B
>error</B
></A
> is signaled if the <VAR CLASS="param"
>external-format</VAR
> is not understood by the <A HREF="26_1_Glossary.html#implementation"
><EM CLASS="term"
>implementation</EM
></A
>. </P
><P CLASS="j"
>The various <A HREF="26_1_Glossary.html#file_system"
><EM CLASS="term"
>file systems</EM
></A
> in existence today have widely differing capabilities, and some aspects of the <A HREF="26_1_Glossary.html#file_system"
><EM CLASS="term"
>file system</EM
></A
> are beyond the scope of this specification to define. A given <A HREF="26_1_Glossary.html#implementation"
><EM CLASS="term"
>implementation</EM
></A
> might not be able to support all of these options in exactly the manner stated. An <A HREF="26_1_Glossary.html#implementation"
><EM CLASS="term"
>implementation</EM
></A
> is required to recognize all of these option keywords and to try to do something &#8220;reasonable&#8221; in the context of the host <A HREF="26_1_Glossary.html#file_system"
><EM CLASS="term"
>file system</EM
></A
>. Where necessary to accomodate the <A HREF="26_1_Glossary.html#file_system"
><EM CLASS="term"
>file system</EM
></A
>, an <A HREF="26_1_Glossary.html#implementation"
><EM CLASS="term"
>implementation</EM
></A
> deviate slightly from the semantics specified here without being disqualified for consideration as a <A HREF="26_1_Glossary.html#conforming_implementation"
><EM CLASS="term"
>conforming implementation</EM
></A
>. If it is utterly impossible for an <A HREF="26_1_Glossary.html#implementation"
><EM CLASS="term"
>implementation</EM
></A
> to handle some option in a manner similar to what is specified here, it may simply signal an error. </P
><P CLASS="j"
>With regard to the <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:element-type</SPAN
></SPAN
> option, if a <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> is requested that is not supported by the <A HREF="26_1_Glossary.html#file_system"
><EM CLASS="term"
>file system</EM
></A
>, a substitution of types such as that which goes on in <A HREF="26_1_Glossary.html#upgrade"
><EM CLASS="term"
>upgrading</EM
></A
> is permissible. As a minimum requirement, it should be the case that opening an <A HREF="26_1_Glossary.html#output"
><EM CLASS="term"
>output</EM
></A
> <A HREF="26_1_Glossary.html#stream"
><EM CLASS="term"
>stream</EM
></A
> to a <A HREF="26_1_Glossary.html#file"
><EM CLASS="term"
>file</EM
></A
> in a given <A HREF="26_1_Glossary.html#element_type"
><EM CLASS="term"
>element type</EM
></A
> and later opening an <A HREF="26_1_Glossary.html#input"
><EM CLASS="term"
>input</EM
></A
> <A HREF="26_1_Glossary.html#stream"
><EM CLASS="term"
>stream</EM
></A
> to the same <A HREF="26_1_Glossary.html#file"
><EM CLASS="term"
>file</EM
></A
> in the same <A HREF="26_1_Glossary.html#element_type"
><EM CLASS="term"
>element type</EM
></A
> should work compatibly.</P
></DD
><DT
><B
>See Also</B
></DT
><DD
><P CLASS="j"
><A HREF="f_with-open-file.html" CLASS="macref"
><B
>with-open-file</B
></A
>, <A HREF="f_close.html" CLASS="funref"
><B
>close</B
></A
>, <A HREF="t_pathname.html" CLASS="typeref"
><B
>pathname</B
></A
>, <A HREF="t_logical-pathname.html" CLASS="typeref"
><B
>logical-pathname</B
></A
>, <A HREF="19_2_Pathnames.html#sec_19_2_3" CLASS="secref"
><SPAN CLASS="cmr"
>Section</SPAN
> <SPAN CLASS="cmr"
>19.2.3</SPAN
> <SPAN CLASS="cmr"
>(Merging</SPAN
> <SPAN CLASS="cmr"
>Pathnames)</SPAN
></A
>, <A HREF="19_1_Overview_of_Filenames.html#sec_19_1_2" CLASS="secref"
><SPAN CLASS="cmr"
>Section</SPAN
> <SPAN CLASS="cmr"
>19.1.2</SPAN
> <SPAN CLASS="cmr"
>(Pathnames</SPAN
> <SPAN CLASS="cmr"
>as</SPAN
> <SPAN CLASS="cmr"
>Filenames)</SPAN
></A
></P
></DD
><DT
><B
>Notes</B
></DT
><DD
><P CLASS="j"
><A HREF="f_open.html" CLASS="funref"
><B
>open</B
></A
> does not automatically close the file when an abnormal exit occurs. </P
><P CLASS="j"
>When <VAR CLASS="param"
>element-type</VAR
> is a <A HREF="26_1_Glossary.html#subtype"
><EM CLASS="term"
>subtype</EM
></A
> of <A HREF="t_character.html" CLASS="typeref"
><B
>character</B
></A
>, <A HREF="f_read-char.html" CLASS="funref"
><B
>read-char</B
></A
> and/or <A HREF="f_write-char.html" CLASS="funref"
><B
>write-char</B
></A
> can be used on the resulting <A HREF="26_1_Glossary.html#file_stream"
><EM CLASS="term"
>file stream</EM
></A
>. </P
><P CLASS="j"
>When <VAR CLASS="param"
>element-type</VAR
> is a <A HREF="26_1_Glossary.html#subtype"
><EM CLASS="term"
>subtype</EM
></A
> of <A HREF="26_1_Glossary.html#integer"
><EM CLASS="term"
>integer</EM
></A
>, <A HREF="f_read-byte.html" CLASS="funref"
><B
>read-byte</B
></A
> and/or <A HREF="f_write-byte.html" CLASS="funref"
><B
>write-byte</B
></A
> can be used on the resulting <A HREF="26_1_Glossary.html#file_stream"
><EM CLASS="term"
>file stream</EM
></A
>. </P
><P CLASS="j"
>When <VAR CLASS="param"
>element-type</VAR
> is <SPAN CLASS="kwd"
><SPAN CLASS="cmtt"
>:default</SPAN
></SPAN
>, the <A HREF="26_1_Glossary.html#type"
><EM CLASS="term"
>type</EM
></A
> can be determined by using <A HREF="f_stream-element-type.html" CLASS="funref"
><B
>stream-element-type</B
></A
>.</P
></DD
></DL
></DIV
></DIV
><DIV CLASS="footer"
><DIV CLASS="btmnav"
><A HREF="f_file-string-length.html" CLASS="prev"
>&#8592;</A
><A HREF="f_stream-external-format.html" CLASS="next"
>&#8594;</A
></DIV
><DIV CLASS="trail"
>Conversion to HTML copyright 2023 by Gilbert Baumann</DIV
></DIV
></DIV
><SCRIPT
>domReady();</SCRIPT
></BODY
></HTML
>
Copy permalink