<?xml version="1.0" encoding="UTF-8"?>

<section id="syscalls"><title>System Calls</title>

<para>The &posix-pac; module makes some system calls available from lisp.
 Not all of these system calls are actually &posix;, so this package has a
 nickname <quote role="package">OS</quote>.  If the package prefix is
 not specified below, the symbol resides in this package.</para>
&base-module;
<simpara>When this module is present, &features-my;
 contains the symbol <constant>:SYSCALLS</constant>.</simpara>

<section id="neworking"><title>Networking</title>
<variablelist>
 <varlistentry id="resolve-host"><term><code>(&resolve-host;
    &optional-amp; &host-r;)</code></term>
 <listitem><para>Returns the <type>HOSTENT</type> structure:
   <variablelist><varlistentry><term><structfield>name</structfield></term>
     <listitem><simpara>host name</simpara></listitem></varlistentry>
    <varlistentry><term><structfield>aliases</structfield></term>
     <listitem><simpara>&list-t; of aliases</simpara></listitem></varlistentry>
    <varlistentry><term><structfield>addr-list</structfield></term>
     <listitem><simpara>&list-t; of &ip; addresses as dotted quads (for IPv4)
       or coloned octets (for IPv6)</simpara></listitem></varlistentry>
    <varlistentry><term><structfield>addrtype</structfield></term>
     <listitem><simpara>&integer-t; address type (IPv4 or IPv6)
   </simpara></listitem></varlistentry></variablelist>
   When &host-r; is omitted or &default-k;, return the data for the
   current host. When &host-r; is &nil;, all the
   host database is returned as a list (this would be the contents of the
   <filename>/etc/hosts</filename> file on a &unix; system or
   <filename>${windir}/system32/etc/hosts</filename> on a &win32; system).
  </para><simpara>This is an interface
   to <function role="unix">gethostent</function>,
   <function role="bsd">gethostbyname</function>,
   and <function role="bsd">gethostbyaddr</function>.</simpara>
 </listitem></varlistentry>
 <varlistentry id="service"><term><code>(OS:SERVICE &optional-amp;
    <replaceable>service-name</replaceable> &proto-r;)</code></term>
 <listitem><simpara>A convenience function for looking up a port given
   the service name, such as <quote>WWW</quote> or <quote>FTP</quote>.
   It returns the <type>SERVICE</type> structure
   (name, list of aliases, port, protocol) for the given
   <replaceable>service-name</replaceable> and &proto-r;,
   or all services as a &list-t; if <replaceable>service-name</replaceable>
   is missing or &nil;.</simpara><simpara>This is an interface
   to <function role="unix">getservent</function>,
   <function role="unix">getservbyname</function>,
   and <function role="unix">getservbyport</function>.</simpara>
</listitem></varlistentry></variablelist></section>

<section id="file-system"><title>File system</title>
<variablelist>
 <varlistentry id="file-stat"><term><code>(POSIX:FILE-STAT
    &path-r; &optional-amp; <replaceable>link-p</replaceable>)</code></term>
  <listitem><para>Return the <type>FILE-STAT</type> structure.
   &path-r; can be a &stream-t;, a &pathname-t;, a &string-t; or a
   &number-t; (on a &unix; system, meaning &file-des;).
   The first slot of the structure returned is the string or the
   number on which <function role="unix">stat</function>,
   &fstat;,
   or <function role="unix">lstat</function> was called.
   The other slots are numbers, members of the <type>struct stat</type>:
    <variablelist>
     <varlistentry><term><structfield>dev</structfield></term>
      <listitem><simpara>Device ID of device containing file.
     </simpara></listitem></varlistentry>
     <varlistentry><term><structfield>ino</structfield></term>
      <listitem><simpara>File serial number.
     </simpara></listitem></varlistentry>
     <varlistentry><term><structfield>mode</structfield></term>
      <listitem><simpara>Mode of file.
     </simpara></listitem></varlistentry>
     <varlistentry><term><structfield>nlink</structfield></term>
      <listitem><simpara>Number of hard links to the file.
     </simpara></listitem></varlistentry>
     <varlistentry><term><structfield>uid</structfield></term>
      <listitem><simpara>User ID of file.
     </simpara></listitem></varlistentry>
     <varlistentry><term><structfield>gid</structfield></term>
      <listitem><simpara>Group ID of file.
     </simpara></listitem></varlistentry>
     <varlistentry><term><structfield>rdev</structfield></term>
      <listitem><simpara>Device ID (if file is character or block
        special).</simpara></listitem></varlistentry>
     <varlistentry><term><structfield>size</structfield></term>
      <listitem><simpara>For regular files, the file size in bytes.
        For symbolic links, the length in bytes of the pathname contained
        in the symbolic link.
        For a shared memory object, the length in bytes.
        For a typed memory object, the length in bytes.
        For other file types, the use of this field is unspecified.
     </simpara></listitem></varlistentry>
     <varlistentry><term><structfield>atime</structfield></term>
      <listitem><simpara>&uni-time; of last access.
     </simpara></listitem></varlistentry>
     <varlistentry><term><structfield>mtime</structfield></term>
      <listitem><simpara>&uni-time; of last data modification.
     </simpara></listitem></varlistentry>
     <varlistentry><term><structfield>ctime</structfield></term>
      <listitem><simpara>&uni-time; of last status change
        (on &win32; - creation time).</simpara></listitem></varlistentry>
     <varlistentry><term><structfield>blksize</structfield></term>
      <listitem><simpara>A file system-specific preferred I/O block size
        for this object.  In some file system types, this may vary from
        file to file.</simpara></listitem></varlistentry>
     <varlistentry><term><structfield>blocks</structfield></term>
      <listitem><simpara>Number of blocks allocated for this object.
     </simpara></listitem></varlistentry></variablelist>
    All slots are read-only.</para>
   <simpara>If the system does not support a particular field (e.g.,
    &win32; prior to 2000 does not have hard links), &nil; (or the
    default, like 1 for the number of hard links for old &win32;) is
    returned.</simpara>
   <note><title>&win32-only;</title>
    <para>Normally, one would expect <code>(POSIX:FILE-STAT
      "foo")</code> and <code>(POSIX:FILE-STAT (&open; "foo"))</code> to
     return <quote>similar</quote> objects (&open;ing a file changes its
     access time though).  This is &not-e; the case on &win32;, where
     <function role="unix">stat</function> works but &fstat; does &not-e;.
     Specifically, &fstat; requires an &int-t; argument of an unknown
     nature, and it is not clear how do deduce it from the &win32; file handle.
     Therefore, instead of always failing on open &file-stream-t; arguments,
     this function calls
     <function role="win32">GetFileInformationByHandle</function> and
     fills the <type>FILE-STAT</type> return value based on that.
 </para></note></listitem></varlistentry>
 <varlistentry id="set-file-stat"><term><code>(POSIX:SET-FILE-STAT
    &path-r; &key-amp; :ATIME :MTIME :MODE :UID :GID)</code></term>
  <listitem><simpara>Set some file attributes using
    <function role="unix">chmod</function>,
    <function role="unix">chown</function>,
    and <function role="unix">utime</function>.
 </simpara></listitem></varlistentry>
 <varlistentry id="stat-vfs"><term><code>(POSIX:STAT-VFS &path-r;)</code></term>
 <listitem><para>Return a <type>STAT-VFS</type> structure.
   &path-r; can be a &stream-t;, a &pathname-t;, a &string-t; or a
   &number-t; (on a &unix; system, meaning &file-des;).
   The first slot of the structure returned is the string
   or the number on which <function role="unix">statvfs</function> or
   <function role="unix">fstatvfs</function> was called.
   The other slots are members of the <type>struct statvfs</type>:
   <variablelist>
    <varlistentry><term><structfield>bsize</structfield></term>
     <listitem><simpara>File system block size.
    </simpara></listitem></varlistentry>
    <varlistentry><term><structfield>frsize</structfield></term>
     <listitem><simpara>Fundamental file system block size.
    </simpara></listitem></varlistentry>
    <varlistentry><term><structfield>blocks</structfield></term>
     <listitem><simpara>Total number of blocks on file system in units of
       <structfield>frsize</structfield>.</simpara></listitem></varlistentry>
    <varlistentry><term><structfield>bfree</structfield></term>
     <listitem><simpara>Total number of free blocks.
    </simpara></listitem></varlistentry>
    <varlistentry><term><structfield>bavail</structfield></term>
     <listitem><simpara>Number of free blocks available to
       non-privileged processes.</simpara></listitem></varlistentry>
    <varlistentry><term><structfield>files</structfield></term>
     <listitem><simpara>Total number of file serial numbers.
    </simpara></listitem></varlistentry>
    <varlistentry><term><structfield>ffree</structfield></term>
     <listitem><simpara>Total number of free file serial numbers.
    </simpara></listitem></varlistentry>
    <varlistentry><term><structfield>favail</structfield></term>
     <listitem><simpara>Number of file serial numbers available to
       non-privileged processes.</simpara></listitem></varlistentry>
    <varlistentry><term><structfield>fsid</structfield></term>
     <listitem><simpara>File system ID.</simpara></listitem></varlistentry>
    <varlistentry><term><structfield>flag</structfield></term>
     <listitem><simpara>List of platform-dependent values, such as &ro-k;.
    </simpara></listitem></varlistentry>
    <varlistentry><term><structfield>namemax</structfield></term>
     <listitem><simpara>Maximum filename length.
   </simpara></listitem></varlistentry>
    <varlistentry><term><structfield>vol-name</structfield></term>
     <listitem><simpara>Volume name (&win32; only).
   </simpara></listitem></varlistentry>
    <varlistentry><term><structfield>fs-type</structfield></term>
     <listitem><simpara>File system type (&win32; only).
   </simpara></listitem></varlistentry></variablelist>
   All slots are read-only.
 </para></listitem></varlistentry>
 <varlistentry id="chroot"><term><code>(POSIX:CHROOT &path-r;)</code></term>
 <listitem><simpara>Change the apparent disk root directory for the current
   running process (and its children) using
   <function role="bsd">chroot</function>.</simpara>
  <simpara>Unless the process has superuser privileges, the operation will
    probably fail with <constant role="errno">EPERM</constant>.</simpara>
 </listitem></varlistentry>
 <varlistentry id="file-tree-walk"><term><code>(POSIX:FILE-TREE-WALK &path-r;
   &func-r; &key-amp; FD-LIMIT CHDIR DEPTH MOUNT PHYS)</code></term>
  <listitem><para>For each object under &path-r; calls &func-r; with 5
   arguments: <orderedlist>
    <listitem><simpara>the pathname of the object</simpara></listitem>
    <listitem><simpara>the <type>FILE-STAT</type> instance containing
     information on the object (or &nil;, see below)</simpara></listitem>
    <listitem><para>a keyword giving additional information.
      Its value is one of the following:<variablelist>
      <varlistentry><term><constant>:F</constant></term>
       <listitem><simpara>The object is a file.
      </simpara></listitem></varlistentry>
      <varlistentry><term><constant>:D</constant></term>
       <listitem><simpara>The object is a directory.
      </simpara></listitem></varlistentry>
      <varlistentry><term><constant>:DP</constant></term>
       <listitem><simpara>The object is a directory and subdirectories have
        been visited. (This condition shall only occur if the
        <constant>:DEPTH</constant> argument is non-&nil;.)
      </simpara></listitem></varlistentry>
      <varlistentry><term><constant>:SL</constant></term>
       <listitem><simpara>The object is a symbolic link. (This condition shall
        only occur if the <constant>PHYS</constant> argument is non-&nil;.)
      </simpara></listitem></varlistentry>
      <varlistentry><term><constant>:SLN</constant></term>
       <listitem><simpara>The object is a symbolic link that does not name an
        existing file. (This condition shall only occur if the
        <constant>PHYS</constant> argument is &nil;.)
      </simpara></listitem></varlistentry>
      <varlistentry><term><constant>:DNR</constant></term>
       <listitem><simpara>The object is a directory that cannot be read.
        The fn function shall not be called for any of its descendants.
      </simpara></listitem></varlistentry>
      <varlistentry><term><constant>:NS</constant></term>
       <listitem><simpara> The <function role="unix">stat</function> function
       failed on the object because of lack of appropriate permission.
       The <type>FILE-STAT</type> argument is &nil;.
       If <function role="unix">stat</function> fails for any other reason,
       and &err-sig;.</simpara></listitem></varlistentry></variablelist>
     </para></listitem>
    <listitem><simpara>the offset of the object's filename in the pathname
     passed as the first argument to &func-r;.</simpara></listitem>
    <listitem><simpara>the depth relative to the root of the walk,
     where the root level is 0.</simpara></listitem></orderedlist></para>
   <simpara>As soon as &func-r; returns non-&nil;, this function returns that
    value; if &func-r; always returns &nil;, then this function also returns
    &nil; when the file tree is exhausted.</simpara>
   <simpara>The <constant>:FD-LIMIT</constant> argument defaults to 5.</simpara>
   <simpara>If <constant>:CHDIR</constant> argument is non-&nil;, the function
    shall change the current working directory to each directory as it reports
    files in that directory</simpara>
   <simpara>If <constant>:DEPTH</constant> argument is non-&nil;, the function
    shall report all files in a directory before reporting the directory
    itself.</simpara>
   <simpara>If <constant>:MOUNT</constant> argument is non-&nil;, the function
    shall only report files in the same file system as &path-r;.</simpara>
   <simpara>If <constant>:PHYS</constant> argument is non-&nil;, the function
    shall perform a physical walk and shall not follow symbolic links.</simpara>
   <simpara>Calls <function role="unix">nftw</function>.</simpara>
  </listitem></varlistentry>
 <varlistentry id="file-info"><term><code>(OS:FILE-INFO &path-r;
    &optional-amp; all)</code></term>
  <listitem><para>Return the <type>FILE-INFO</type> structure.
    &path-r; should be a &path-des;. The 7 slots are<simplelist columns="1">
     <member><structfield>attributes</structfield></member>
     <member><structfield>ctime</structfield></member>
     <member><structfield>atime</structfield></member>
     <member><structfield>wtime</structfield></member>
     <member><structfield>size</structfield></member>
     <member><structfield>name</structfield></member>
     <member><structfield>name-short</structfield></member>
    </simplelist>When &path-r; is wild, returns just the first match,
    unless the second (optional) argument is non-&nil;, in which case a
    &list-t; of objects is returned, one for each match.
 </para></listitem></varlistentry>
 <varlistentry id="stream-lock"><term><code>(POSIX:STREAM-LOCK &stream-r;
    <replaceable>lock-p</replaceable> &key-amp;
    (:BLOCK &t;) (:SHARED &nil;) (:START 0) (:END &nil;))</code></term>
  <listitem><simpara>Set or remove a file lock for the (portion of the)
    file associated with &stream-r;,
    depending on <replaceable>lock-p</replaceable>.
    When <replaceable>block</replaceable> is &nil;, the call is non-blocking,
    and when locking fails, it returns &nil;.
    When <replaceable>shared</replaceable> is non-&nil;,
    then lock can be shared between several callers.
    Several processes can set a <replaceable>shared</replaceable>
    (i.e., <emphasis>read</emphasis>) lock, but only one can set
    an <replaceable>exclusive</replaceable> (i.e., <emphasis>write</emphasis>,
    or non-<replaceable>shared</replaceable>) lock.
    Uses <function role="unix">fcntl</function>
    or <function role="win32">LockFileEx</function>.</simpara>
   <warning><simpara>&unix; and &win32; differ on locking 0-length files: on
     &win32;, two processes can have exclusive locks on it!</simpara></warning>
   <warning><simpara>&win32; locks are <emphasis>mandatory</emphasis>:
     if you lock a file, others will not be able to open it!</simpara>
    <simpara>&unix; locks are usually <emphasis>advisory</emphasis>: a process
     is free to ignore it, but on some &unix; systems one can mount some
     file system with <emphasis>mandatory</emphasis> locks.</simpara></warning>
 </listitem></varlistentry>
 <varlistentry id="with-stream-lock"><term><code>(POSIX:WITH-STREAM-LOCK
    (&stream-r; &rest-amp; &options-r;) &body-amp; &body-r;)</code></term>
  <listitem><simpara>Lock the &stream-r;, execute the &body-r;, unlock
    the &stream-r;.  Pass &options-r; to &stream-lock;.
 </simpara></listitem></varlistentry>
 <varlistentry id="fcntl"><term><code>(&stream-options;
    &stream-r; &command-r; &optional-amp; &value-r;)</code></term>
  <listitem><simpara>Call <function role="unix">fcntl</function>,
    &command-r; can be <constant>:FD</constant> or <constant>:FL</constant>.
 </simpara><simpara>When &value-r; is missing, the option is queried and
  the value is returned; if &value-r; is supplied, the option is set and
  no values are returned.</simpara></listitem></varlistentry>
 <varlistentry id="file-size"><term><code>(&file-size; &file-r;)</code></term>
  <term><code>(&setf; (&file-size; &file-r;) &size-r;)</code></term>
  <listitem><simpara>Extend &file-length; to operate on &path-des;s.</simpara>
   <simpara>Set the &size-r; of a &file-r; using
    <function role="unix">ftruncate</function> (if &file-r; is an open
    &file-stream-t;) or <function role="unix">truncate</function> (if
    &file-r; is a &path-des;).</simpara>
   <simpara>Use <function role="win32">SetFilePointerEx</function>
    and <function role="win32">SetEndOfFile</function> on &win32;.
 </simpara></listitem></varlistentry>
 <varlistentry id="mknod"><term><code>(POSIX:MKNOD &path-r; &type-r;
    &mode-r;)</code></term>
 <listitem><simpara>Create a special file using
   <function role="unix">mknod</function>.
   Use <constant>:FIFO</constant> to create pipes
   and <constant>:SOCK</constant> to create sockets.
 </simpara></listitem></varlistentry>
 <varlistentry id="convert-mode">
  <term><code>(POSIX:CONVERT-MODE &mode-r;)</code></term>
  <listitem><simpara>Convert between numeric, (e.g., <literal>0644</literal>)
    and symbolic (e.g., <literal role="data">(:RUSR :WUSR :RGRP
     :ROTH)</literal>) file modes.</simpara></listitem></varlistentry>
 <varlistentry id="umask"><term><code>(POSIX:UMASK &mode-r;)</code></term>
 <listitem><simpara>Change process mask using
   <function role="unix">umask</function>.
 </simpara></listitem></varlistentry>
 <varlistentry id="copy-file"><term><code>(&copy-file; &source-r; &dest-r;
    &key-amp; :METHOD :PRESERVE :IF-EXISTS :IF-DOES-NOT-EXIST)</code></term>
  <listitem><simpara>This is an interface to
    <function role="unix">symlink</function>
    (when &method-r; is <constant>:SYMLINK</constant>),
    <function role="unix">link</function>
    (when it is <constant>:HARDLINK</constant>),
    and <function role="unix">rename</function>
    (when it is <constant>:RENAME</constant>) system calls, as well as,
    you guessed it, a generic file copy utility (when &method-r; is &copy-k;).
   </simpara><simpara>When &method-r; is <constant>:HARDLINK-OR-COPY</constant>
    and <function role="unix">link</function> fails (e.g., because the
    &source-r; and &dest-r; are on different devices), fall back to &copy-k;.
   </simpara><simpara>Both &source-r; and &dest-r; may be wild, in which
    case &translate-pathname; is used.</simpara>
   <simpara>When <replaceable>preserve</replaceable> is non-&nil;, try
    to duplicate the time, owner, and permission characteristics of each
    source file in the corresponding destination file,
    similar to <command role="unix">cp -p</command>.</simpara>
   <simpara>The meaning and defaults of &if-exists; and
    &if-does-not-exist; are the same as in &open;.</simpara>
   <simpara>The actual &dest-r; file created is
    <code>(&merge-pathnames; &source-r; &dest-r;)</code> so that
    <code>(&copy-file; "foo" "dir/")</code> creates
    <filename>"dir/foo"</filename> and
    <code>(&copy-file; "foo.csv" "bar")</code> creates
    <filename>"bar.csv"</filename>.
    If you want to actually copy <filename>"foo.csv"</filename> to
    <filename>"bar"</filename>, do
    <code>(&copy-file; (&make-pathname; :name "foo.csv") "bar")</code>.
 </simpara></listitem></varlistentry>
 <varlistentry id="dup-handle"><term><code>(&dup-handle;
    <replaceable>fd1</replaceable> &optional-amp;
    <replaceable>fd2</replaceable>)</code></term>
  <listitem><simpara>This is an interface to the &dup; system calls on
    &unix; systems and to <function role="win32">DuplicateHandle</function>
    system call on &win32;.</simpara></listitem></varlistentry>
 <varlistentry id="shortcut-info"><term><code>(OS:SHORTCUT-INFO
    &path-r;)</code></term>
  <listitem><simpara>Return information about a &win32; shortcut
    (<filename>#P".lnk"</filename>) file contents in a
    <type>SHORTCUT-INFO</type> structure.</simpara></listitem></varlistentry>
 <varlistentry id="make-shortcut"><term><code>(OS:MAKE-SHORTCUT &path-r;
    &key-amp; :WORKING-DIRECTORY :ARGUMENTS :SHOW-COMMAND :ICON :DESCRIPTION
    :HOT-KEY :PATH)</code></term>
  <listitem><simpara>Create (or modify the properties of an existing one)
    a &win32; shortcut (<filename>#P".lnk"</filename>) file.
 </simpara></listitem></varlistentry>
 <varlistentry id="file-properties"><term><code>(OS:FILE-PROPERTIES
    filename set &key-amp; :INITID &allow-other-keys-amp;)</code></term>
  <listitem><para>Wrapper for the &win32;
    <function role="win32">IPropertyStorage</function> functionality.
    <variablelist><varlistentry><term>&filename-r;</term>
      <listitem><simpara>name of a compound file (where properties are stored)
      or (on NTFS) name of any file (properties are stored in the filesystem).
      For compound files on NTFS, file storage is preferred.
     </simpara></listitem></varlistentry>
     <varlistentry><term><replaceable>set</replaceable></term>
      <listitem><simpara>property set, either <constant>:BUILT-IN</constant>
        or <constant>:USER-DEFINED</constant>
     </simpara></listitem></varlistentry>
     <varlistentry><term><constant>:INITID</constant>
       <replaceable>init-id</replaceable></term>
      <listitem><simpara>set the <replaceable>init-id</replaceable>
     </simpara></listitem></varlistentry>
     <varlistentry><term><replaceable>specifier value</replaceable></term>
      <listitem><para><variablelist>
         <varlistentry><term><replaceable>specifier</replaceable></term>
          <listitem><para>the property specifier: an &integer-t;,
            &keyword-t;, &string-t; or a &list-t; of an &integer-t; or a
            &keyword-t; and a &string-t;.
            <variablelist><varlistentry><term>&integer-t;</term>
              <listitem><simpara>a property identifier
             </simpara></listitem></varlistentry>
             <varlistentry><term>&keyword-t;</term>
              <listitem><para>Predefined &keyword-t; IDs are
                <simplelist columns="4">
                 <member><constant>:APPNAME</constant></member>
                 <member><constant>:AUTHOR</constant></member>
                 <member><constant>:CHARCOUNT</constant></member>
                 <member><constant>:CODEPAGE</constant></member>
                 <member><constant>:COMMENTS</constant></member>
                 <member><constant>:CREATE-DTM</constant></member>
                 <member><constant>:DOC-SECURITY</constant></member>
                 <member><constant>:EDITTIME</constant></member>
                 <member><constant>:KEYWORDS</constant></member>
                 <member><constant>:LASTAUTHOR</constant></member>
                 <member><constant>:LASTPRINTED</constant></member>
                 <member><constant>:LASTSAVE-DTM</constant></member>
                 <member><constant>:LOCALE</constant></member>
                 <member><constant>:PAGECOUNT</constant></member>
                 <member><constant>:REVNUMBER</constant></member>
                 <member><constant>:SUBJECT</constant></member>
                 <member><constant>:TEMPLATE</constant></member>
                 <member><constant>:THUMBNAIL</constant></member>
                 <member><constant>:TITLE</constant></member>
                 <member><constant>:WORDCOUNT</constant></member>
             </simplelist></para></listitem></varlistentry>
             <varlistentry><term>&string-t;</term>
              <listitem><simpara>string property specifier.
                If no match is found, the first ID &gt;= init-id
                (which defaults to 2) is associated with the
                string and its value is replaced with new value.
             </simpara></listitem></varlistentry>
             <varlistentry><term>(&integer-t;|&keyword-t;
               &string-t;)</term>
              <listitem><simpara>the first element is used as
                a specifier, the string is associated with this ID.
            </simpara></listitem></varlistentry></variablelist>
           </para></listitem></varlistentry>
         <varlistentry><term>&value-r;</term>
          <listitem><para>the new value of the property, a suitable Lisp
            object, &nil; or a &list-t; of a &keyword-t; and the value
            itself.  If &value-r; is &nil;, no assignment is done.
            <constant>:EMPTY</constant> and <constant>:NULL</constant>
            correspond to the <type>VT_EMPTY</type>
            and <type>VT_NULL</type> data types.
            &keyword-t; in the &list-t; specifies the desired type of
            the property being set.
            Supported types are<simplelist columns="4">
             <member><constant>:BOOL</constant></member>
             <member><constant>:BSTR</constant></member>
             <member><constant>:DATE</constant></member>
             <member>&error-k;</member>
             <member><constant>:FILETIME</constant></member>
             <member><constant>:I1</constant></member>
             <member><constant>:I2</constant></member>
             <member><constant>:I4</constant></member>
             <member><constant>:I8</constant></member>
             <member><constant>:LPSTR</constant></member>
             <member><constant>:LPWSTR</constant></member>
             <member><constant>:R4</constant></member>
             <member><constant>:R8</constant></member>
             <member><constant>:UI1</constant></member>
             <member><constant>:UI2</constant></member>
             <member><constant>:UI4</constant></member>
             <member><constant>:UI8</constant></member>
             <member><constant>:UINT</constant></member></simplelist>
            <type>FILETIME</type>s are converted to/from the universal
            time format, while <type>DATE</type>s are not.
       </para></listitem></varlistentry></variablelist>
    </para></listitem></varlistentry></variablelist>
    Returns the property contents before assignment as multiple values.
 </para></listitem></varlistentry>
 <varlistentry id="file-owner"><term><code>(OS:FILE-OWNER
    &filename-r;)</code></term>
  <listitem><simpara>Return the owner of the file.</simpara>
   <simpara>&unix-w32-only;</simpara></listitem></varlistentry>
 <varlistentry id="mkstemp"><term><code>(POSIX:MKSTEMP &filename-r;
    &key-amp; &direction-k; &eltype; &extfmt; &buffered;)</code></term>
  <listitem><simpara>Calls <function role="unix">mkstemp</function>;
    returns a &file-stream-t;.</simpara>
   <simpara>&direction-k; should allow output.</simpara>
 </listitem></varlistentry>
 <varlistentry id="mkdtemp"><term><code>(POSIX:MKDTEMP
    &filename-r;)</code></term>
  <listitem><simpara>Calls <function role="unix">mkdtemp</function>;
    creates a new empty temporary directory and returns its namestring.
 </simpara></listitem></varlistentry>
 <varlistentry id="sync"><term><code>(POSIX:SYNC &optional-amp;
    &stream-r;)</code></term>
  <listitem><simpara>Calls <function role="unix">fsync</function>
    (<function role="win32">FlushFileBuffers</function> on &win32;)
    on the &file-des; associated with &stream-r;,
    or <function role="unix">sync</function>
    when &stream-r; is not supplied</simpara></listitem></varlistentry>
</variablelist></section>

<section id="user-group"><title>Users and Groups</title>
<variablelist>
 <varlistentry id="user-info"><term><code>(POSIX:USER-INFO
    &optional-amp; &user-r;)</code></term>
 <listitem><simpara>Return the <type>USER-INFO</type> structure (name,
   encoded password, UID, GID, full name, home directory, shell).
   &user-r; should be a &string-t;
   (<function role="unix">getpwnam</function> is used) or an &integer-t;
   (<function role="unix">getpwuid</function> is used).
   When &user-r; is missing or &nil;, return all
   users (using <function role="unix">getpwent</function>).
   When &user-r; is &default-k;, return the information about the current user
   (using <function role="unix">getlogin</function>).</simpara>
  <simpara>&unix-only;</simpara></listitem></varlistentry>
<varlistentry id="group-info"><term><code>(POSIX:GROUP-INFO
    &optional-amp; <replaceable>group</replaceable>)</code></term>
 <listitem><simpara>Return the <type>GROUP-INFO</type> structure (name,
   GID, member &list-t;). <replaceable>group</replaceable> should be a
   &string-t; (<function role="unix">getgrnam</function> is used) or an
   &integer-t; (<function role="unix">getgrgid</function> is used).
   When <replaceable>group</replaceable> is missing or &nil;, return all
   groups (using <function role="unix">getgrent</function>).</simpara>
  <simpara>&unix-only;</simpara></listitem></varlistentry>
<varlistentry id="user-shells"><term><code>(POSIX:USER-SHELLS)</code></term>
 <listitem><simpara>Call <function role="bsd">getusershell</function>.
</simpara></listitem></varlistentry>
<varlistentry id="get-user-sid"><term><code>(OS:GET-USER-SID
   &optional-amp; &user-r;)</code></term>
 <listitem><simpara>Call <function role="win32">LookupAccountName</function>
  on &user-r; or, if that is not supplied, call
  <function role="win32">OpenProcessToken</function>,
  <function role="win32">GetTokenInformation</function>, and then
  <function role="win32">ConvertSidToStringSid</function> on
  <structfield>User.Sid</structfield>.</simpara></listitem></varlistentry>
</variablelist></section>

<section id="sysinfo"><title>System Information</title>
<variablelist>
 <varlistentry id="uname"><term><code>(POSIX:UNAME)</code></term>
  <listitem><simpara>Return a structure describing the OS, derived from
    <function role="unix">uname</function>.</simpara></listitem></varlistentry>
 <varlistentry id="sysconf">
  <term><code>(POSIX:SYSCONF &optional-amp; &what-r;)</code></term>
  <term><code>(POSIX:CONFSTR &optional-amp; &what-r;)</code></term>
  <listitem><simpara>Return the specified configuration parameter or a
    &plist; of all available parameters (when &what-r; is missing or
    &nil;), by calling <function role="unix">sysconf</function>
    and <function role="unix">confstr</function> respectively.
 </simpara></listitem></varlistentry>
 <varlistentry id="pathconf"><term><code>(POSIX:PATHCONF &path-r;
    &optional-amp; &what-r;)</code></term>
  <listitem><simpara>Return the specified configuration parameter or a
    &plist; of all available parameters (when &what-r; is missing or
    &nil;), by calling <function role="unix">fpathconf</function> on
    open file streams and <function role="unix">pathconf</function> on
    all other &path-des;s.</simpara></listitem></varlistentry>
 <varlistentry id="rlimit"><term><code>(&rlimit;
    &optional-amp; &what-r;)</code></term>
  <listitem><simpara>Return the current and the maximal limits as two
    values when &what-r; is specified or the &plist; of all available
    limits (as an <type>RLIMIT</type> structure) when &what-r; is
    missing or &nil;, by calling <function role="unix">getrlimit</function>.
 </simpara></listitem></varlistentry>
 <varlistentry id="set-rlimit"><term><code>(&setf; (&rlimit; &what-r;)
    (&values; <replaceable>cur</replaceable>
    <replaceable>max</replaceable>))</code></term>
  <term><code>(&setf; (&rlimit; &what-r;)
    <replaceable>rlimit</replaceable>)</code></term>
  <term><code>(&setf; (&rlimit;)
    <replaceable>rlimit-plist</replaceable>)</code></term>
  <listitem><para>Set the limits using
    <function role="unix">setrlimit</function>.<orderedlist>
     <listitem><simpara>In the first form, <replaceable>cur</replaceable>
       and <replaceable>max</replaceable> are numbers
       (or &nil; for <constant>RLIM_INFINITY</constant>).</simpara></listitem>
     <listitem><simpara>In the second form, <replaceable>rlimit</replaceable>
       is an <type>RLIMIT</type> structure.</simpara></listitem>
     <listitem><simpara>In the third form,
       <replaceable>rlimit-plist</replaceable> is a &plist;, as returned by
       <code>(&rlimit;)</code>.</simpara></listitem>
 </orderedlist></para></listitem></varlistentry>
 <varlistentry id="usage"><term><code>(&usage;
   &optional-amp; &what-r;)</code></term>
  <listitem><simpara>Return the <type>USAGE</type> structure describing the
   resource usage of the thread, process, or its children, using
   <function role="unix">getrusage</function>. WHen &what-r; is missing
   or &nil;, return all available data as a &plist;.
 </simpara></listitem></varlistentry>
 <varlistentry id="bogomips"><term><code>(POSIX:BOGOMIPS)</code></term>
  <listitem><simpara>Compute the
    <ulink url="http://en.wikipedia.org/wiki/BogoMips">BogoMips</ulink>
    rating.</simpara></listitem></varlistentry>
 <varlistentry id="loadavg"><term><code>(POSIX:LOADAVG &optional-amp;
    percentp)</code></term>
  <listitem><simpara>Return 1, 5, and 15 minute system load averages,
    retrieved by <function role="bsd">getloadavg</function>.
    If the argument is specified and non-&nil;, the values are returned
    as integer percentiles.</simpara></listitem></varlistentry>
 <varlistentry><term><code>(OS:SYSTEM-INFO)</code></term>
  <listitem><simpara>Return &win32; system information in a
    <type>SYSTEM-INFO</type> structure.</simpara></listitem></varlistentry>
 <varlistentry><term><code>(OS:VERSION)</code></term>
  <listitem><simpara>Return &win32; version information in a
    <type>VERSION</type> structure.</simpara></listitem></varlistentry>
 <varlistentry><term><code>(OS:MEMORY-STATUS)</code></term>
  <listitem><simpara>Return &win32; memory status information in a
    <type>MEMORY-STATUS</type> structure.</simpara></listitem></varlistentry>
 <varlistentry id="phys-mem"><term><code>(OS:PHYSICAL-MEMORY)</code></term>
  <listitem><simpara>Return 2 values: total and available physical memory.
   </simpara><simpara>&unix-w32-only;</simpara></listitem></varlistentry>
 <varlistentry id="hostid"><term><code>(OS:HOSTID)</code></term>
  <term><code>(&setf; (OS:HOSTID) &value-r;)</code></term>
  <listitem><simpara>Call <function role="unix">gethostid</function> and
    return a (hopefully) universally unique &integer-t; identifier of
    this machine.</simpara>
   <warning><para>On &linux; this number appears to be the IPv4 32-bit
     address with the first 2 bytes and the last 2 bytes swapped:
<programlisting language="lisp">(&convert-address; :inet (os:hostid))
<computeroutput>"7.3.192.168"</computeroutput>
(first (posix:hostent-addr-list (&resolve-host; :default)))
<computeroutput>"192.168.7.3"</computeroutput></programlisting>This, of
course, means that <quote>universally unique</quote> it is &not-e;.
   </para></warning><simpara>Superuser can also set host identifier
    using &setf; which calls <function role="bsd">sethostid</function>.
   </simpara><simpara>&unix-w32-only;</simpara></listitem></varlistentry>
 <varlistentry id="domainname"><term><code>(OS:DOMAINNAME)</code></term>
  <term><code>(&setf; (OS:DOMAINNAME) &dom-r;)</code></term>
  <listitem><simpara>Call <function role="bsd">getdomainname</function>
    and <function role="bsd">setdomainname</function>.</simpara></listitem>
</varlistentry></variablelist></section>

<section id="posix-math"><title>Mathematical functions</title>
<para>We implement access to <simplelist columns="1">
  <member><code>(<function role="unix">erf</function> &real-r;)</code></member>
  <member><code>(<function role="unix">erfc</function> &real-r;)</code></member>
  <member><code>(<function role="unix">j0</function> &real-r;)</code></member>
  <member><code>(<function role="unix">j1</function> &real-r;)</code></member>
  <member><code>(<function role="unix">jn</function> &int-r;
    &real-r;)</code></member>
  <member><code>(<function role="unix">y0</function> &real-r;)</code></member>
  <member><code>(<function role="unix">y1</function> &real-r;)</code></member>
  <member><code>(<function role="unix">yn</function> &int-r;
    &real-r;)</code></member>
  <member><code>(<function role="unix">tgamma</function>
    &real-r;)</code></member>
  <member><code>(<function role="unix">lgamma</function>
    &real-r;)</code></member></simplelist>
which compute the error functions, Bessel functions and Gamma.</para>
<simpara>These functions are required by the &posix; standard and should
 be declared in <filename role="unix">math.h</filename>.</simpara>
<warning><simpara>Please note that these functions do &not-e; provide
  lisp-style error handling and precision, and do all the computations
  at the &double-float-t; level.</simpara></warning>
<para>Function <code>(<function role="unix">ffs</function> &n-r;)</code>
 finds the first bit set. It is implemented in pure Lisp and supports
 &bignum-t;s.</para>
</section>

<section id="encryption"><title>Encryption</title>
<para>The functionss <term><code>POSIX:CRYPT</code></term>,
 <term><code>POSIX:ENCRYPT</code></term>, and
 <term><code>POSIX:SETKEY</code></term> are no longer implemented, since
 they are no longer considered secure.</para></section>

<section id="sys-log"><title>Syslog</title>
<variablelist>
 <varlistentry id="openlog"><term><code>(POSIX:OPENLOG ident &key-amp;
    :PID :CONS :NDELAY :ODELAY :NOWAIT :FACILITY)</code></term>
  <listitem><simpara>Calls <function role="unix">openlog</function>
 </simpara></listitem></varlistentry>
 <varlistentry id="setlogmask"><term><code>(POSIX:SETLOGMASK
    maskpri)</code></term>
  <listitem><simpara>Calls <function role="unix">setlogmask</function>.
 </simpara></listitem></varlistentry>
 <varlistentry id="syslog"><term><code>(POSIX:SYSLOG severity facility
    &fmt-r; &rest-amp; &args-r;)</code></term>
  <listitem><simpara>Calls <function role="unix">syslog</function> on
    <code>(&apply; &format; &nil; &fmt-r; &args-r;)</code>.</simpara>
   <simpara>No <literal role="data">%</literal> conversion is performed,
    you must do all formatting in Lisp.</simpara></listitem></varlistentry>
 <varlistentry id="closelog"><term><code>(POSIX:CLOSELOG)</code></term>
  <listitem><simpara>Calls <function role="unix">closelog</function>.
</simpara></listitem></varlistentry></variablelist></section>

<section id="processes"><title>Processes</title>
<variablelist>
 <varlistentry id="process-id"><term><code>(OS:PROCESS-ID)</code></term>
  <listitem><simpara>Return the process ID
    (on &unix; calls <function role="unix">getpid</function>,
    on &win32; calls <function role="win32">GetCurrentProcessId</function>)
 </simpara></listitem></varlistentry>
 <varlistentry id="priority"><term><code>(OS:PRIORITY &pid-r;
    &optional-amp; &what-r;)</code></term>
  <term><code>(&setf; (OS:PRIORITY &pid-r; &optional-amp; &what-r;)
    priority)</code></term>
  <listitem><para>Return or set the process priority, platform-dependent
    &integer-t; or platform-independent &symbol-t;, one of
    <simplelist columns="3">
     <member><constant>:REALTIME</constant></member>
     <member><constant>:HIGH</constant></member>
     <member><constant>:ABOVE-NORMAL</constant></member>
     <member><constant>:NORMAL</constant></member>
     <member><constant>:BELOW-NORMAL</constant></member>
     <member><constant>:LOW</constant></member>
     <member><constant>:IDLE</constant></member></simplelist>
    On &unix; calls <function role="unix">getpriority</function>
    and <function role="unix">setpriority</function>, on
    &win32; calls <function role="win32">GetPriorityClass</function> and
    <function role="win32">SetPriorityClass</function>.</para>
 </listitem></varlistentry>
 <varlistentry id="kill"><term><code>(POSIX:KILL &pid-r; &sig-r;)</code></term>
  <listitem><simpara>Calls <function role="unix">kill</function>.
 </simpara></listitem></varlistentry>
 <varlistentry id="getppid"><term><code>(POSIX:GETPPID)</code></term>
  <listitem><simpara>Calls <function role="unix">getppid</function>.
 </simpara></listitem></varlistentry>
 <varlistentry id="getpgrp"><term><code>(POSIX:GETPGRP)</code></term>
  <listitem><simpara>Calls <function role="unix">getpgrp</function>.
 </simpara></listitem></varlistentry>
 <varlistentry id="setpgrp"><term><code>(POSIX:SETPGRP)</code></term>
  <listitem><simpara>Calls <function role="unix">setpgrp</function>;
    on non-&posix; systems where it requires 2 arguments (legacy
    BSD-style), it is called as <code>setpgrp(0,0)</code>.
 </simpara></listitem></varlistentry>
 <varlistentry id="getsid"><term><code>(POSIX:GETSID &pid-r;)</code></term>
  <listitem><simpara>Calls <function role="unix">getsid</function>.
 </simpara></listitem></varlistentry>
 <varlistentry id="setsid"><term><code>(POSIX:SETSID)</code></term>
  <listitem><simpara>Calls <function role="unix">setsid</function>.
 </simpara></listitem></varlistentry>
 <varlistentry id="getpgid"><term><code>(POSIX:PGID &pid-r;)</code></term>
  <term><code>(&setf; (POSIX:PGID &pid-r;)
    <replaceable>pgid</replaceable>)</code></term>
  <listitem><simpara>Call <function role="unix">getpgid</function> and
   <function role="unix">setpgid</function>.</simpara></listitem></varlistentry>
 <varlistentry id="setreuid"><term><code>(POSIX:SETREUID
    ruid euid)</code></term>
  <listitem><simpara>Call <function role="unix">setreuid</function>.
 </simpara></listitem></varlistentry>
 <varlistentry id="setregid"><term><code>(POSIX:SETREGID
    rgid egid)</code></term>
  <listitem><simpara>Call <function role="unix">setregid</function>.
 </simpara></listitem></varlistentry>
 <varlistentry id="getuid"><term><code>(POSIX:UID)</code></term>
  <term><code>(&setf; (POSIX:UID) &uid-r;)</code></term>
  <listitem><simpara>Call <function role="unix">getuid</function> and
   <function role="unix">setuid</function>.</simpara></listitem></varlistentry>
 <varlistentry id="getgid"><term><code>(POSIX:GID)</code></term>
  <term><code>(&setf; (POSIX:GID) &gid-r;)</code></term>
  <listitem><simpara>Call <function role="unix">getgid</function> and
   <function role="unix">setgid</function>.</simpara></listitem></varlistentry>
 <varlistentry id="geteuid"><term><code>(POSIX:EUID)</code></term>
  <term><code>(&setf; (POSIX:EUID) &uid-r;)</code></term>
  <listitem><simpara>Call <function role="unix">geteuid</function> and
   <function role="unix">seteuid</function>.</simpara></listitem></varlistentry>
 <varlistentry id="getegid"><term><code>(POSIX:EGID)</code></term>
  <term><code>(&setf; (POSIX:EGID) &gid-r;)</code></term>
  <listitem><simpara>Call <function role="unix">getegid</function> and
   <function role="unix">setegid</function>.</simpara></listitem></varlistentry>
 <varlistentry id="getgroups"><term><code>(POSIX:GROUPS)</code></term>
  <term><code>(&setf; (POSIX:GROUPS) &list-r;)</code></term>
  <listitem><simpara>Call <function role="unix">getgroups</function> and
   <function role="bsd">setgroups</function>.
 </simpara></listitem></varlistentry>
 <varlistentry id="wait"><term><code>(&wait; &key-amp; :PID :USAGE
    :NOHANG :UNTRACED :STOPPED :EXITED :CONTINUED :NOWAIT)</code></term>
  <listitem><simpara>Wait for termination of the child process
    <constant>:PID</constant> (or any child process if not specified).</simpara>
   <simpara>If <constant>:NOHANG</constant> is specifed, return &zero;
    as the only value immediately if no child process has terminated.</simpara>
   <simpara>Otherwise, the first return value is the &pid-r; of the
    terminated child process.</simpara>
   <para>The second and third return values depend on the way the
    process terminated:<variablelist>
     <varlistentry><term>2nd value = <constant>:EXITED</constant></term>
      <term>3rd value = <replaceable>exit status</replaceable></term>
      <listitem><simpara>if the child terminated normally, e.g., by
        calling <function role="unix">exit</function>.
     </simpara></listitem></varlistentry>
     <varlistentry><term>2nd value = <constant>:SIGNALED</constant></term>
      <term>3rd value = &sig-r;</term>
      <listitem><simpara>if the child process was terminated by a &sig-r;.
     </simpara></listitem></varlistentry>
     <varlistentry><term>2nd value = <constant>:STOPPED</constant></term>
      <term>3rd value = &sig-r;</term>
      <listitem><simpara>if the child process was stopped by delivery of
        a &sig-r;.</simpara></listitem></varlistentry>
     <varlistentry><term>2nd value = <constant>:CONTINUED</constant></term>
      <term>3rd value = &nil;</term>
      <listitem><simpara>if the child process has continued from a job
        control stop.</simpara></listitem></varlistentry>
     <varlistentry><term>2nd value = &nil;</term>
      <term>3rd value = &number-r;</term>
      <listitem><simpara>if &clisp; could not figure out what has happened.
        Please read your local <function role="unix">waitpid</function>
        manual and send us a patch.</simpara></listitem></varlistentry>
     </variablelist></para>
   <simpara>The fourth value is only returned if <constant>:USAGE</constant>
    is non-&nil; and in that case it is a structure describing resource
    usage by the terminated process, similar to what &usage; returns.</simpara>
   <simpara>To avoid race conditions, it is important to start your
    subprocesses &and-e; &wait; for them inside the &body-r; of
    a &with-subprocesses; form.</simpara>
   <simpara>Calls <function role="unix">waitpid</function> and
    (when the <constant>:USAGE</constant> argument is non-&nil;)
    <function role="bsd">wait4</function>.</simpara></listitem></varlistentry>
 <varlistentry id="with-subprocesses"><term><code>(&with-subprocesses;
    &body-amp;)</code></term>
   <listitem><simpara>Evaluate &body-r; while receiving signals from
   subprocesses; your &run-prog; and related &wait; calls should be
   inside it.</simpara></listitem></varlistentry>
</variablelist></section>

<section id="accounting"><title>Accounting</title>
<variablelist>
 <varlistentry id="endutxent"><term><code>(POSIX:ENDUTXENT)</code></term>
  <listitem><simpara>Calls <function role="unix">endutxent</function>.
 </simpara></listitem></varlistentry>
 <varlistentry id="getutxent"><term><code>(POSIX:GETUTXENT
    &optional-amp; utmpx)</code></term>
  <listitem><simpara>Calls <function role="unix">getutxent</function>,
    returns a &structure-object-t; of type <type>POSIX:UTMPX</type>,
    which can be passed to subsequent calls to this function and re-used.
 </simpara></listitem></varlistentry>
 <varlistentry id="getutxid"><term><code>(POSIX:GETUTXID id)</code></term>
  <listitem><simpara>Calls <function role="unix">getutxid</function>,
    the argument is filled and returned.</simpara></listitem></varlistentry>
 <varlistentry id="getutxline"><term><code>(POSIX:GETUTXLINE line)</code></term>
  <listitem><simpara>Calls <function role="unix">getutxline</function>,
    the argument is filled and returned.</simpara></listitem></varlistentry>
 <varlistentry id="pututxline"><term><code>(POSIX:PUTUTXLINE
    utmpx)</code></term>
  <listitem><simpara>Calls <function role="unix">pututxline</function>,
    the argument is filled and returned.</simpara></listitem></varlistentry>
 <varlistentry id="setutxent"><term><code>(POSIX:SETUTXENT)</code></term>
  <listitem><simpara>Calls <function role="unix">setutxent</function>.
</simpara></listitem></varlistentry></variablelist></section>

<section id="posix-time"><title>Time and Data Conversion</title>
<variablelist><varlistentry id="strtime"><term><code>(OS:STRING-TIME
  &fmt-r; &optional-amp; &object-r; timezone)</code></term>
  <listitem><itemizedlist><listitem><simpara>When &object-r; is a &string-t;,
   it is parsed into a universal time according to &fmt-r; by
   <function role="unix">strptime</function>.</simpara></listitem>
   <listitem><simpara>When it is an &integer-t;, it is formatted according
    to &fmt-r; by <function role="unix">strftime</function>.
    &object-r; defaults to <code>(&get-universal-time;)</code>.
</simpara></listitem></itemizedlist></listitem></varlistentry>
<varlistentry id="getdate"><term><code>(OS:GETDATE &string-r;
   &optional-amp; timezone)</code></term>
 <listitem><simpara>Parse the &string-r; into a universal time using
  <function role="unix">getdate</function>.</simpara>
  <simpara>If the the &env-var; <envar>DATEMSK</envar> is not set when
   &clisp; is invoked, &clisp; sets it to point to the file
   <filename role="clisp">modules/syscalls/datemsk</filename>, installed as
   <code>(&merge-pathnames; "syscalls/datemsk" &libdir;)</code>.
</simpara></listitem></varlistentry></variablelist></section>

<section id="strverscmp"><title>String comparision</title>
<para>Functions <simplelist columns="1">
 <member><code>(OS:VERSION&lt; &x1-r; &x2-r;)</code></member>
 <member><code>(OS:VERSION&lt;= &x1-r; &x2-r;)</code></member>
 <member><code>(OS:VERSION&gt; &x1-r; &x2-r;)</code></member>
 <member><code>(OS:VERSION&gt;= &x1-r; &x2-r;)</code></member></simplelist>
 compare two &string-t;s as version numbers (e.g.,
 <literal role="data">"foo10"</literal> is <emphasis>greater</emphasis> than
 <literal role="data">"foo9"</literal>) using
 <function role="gnu">strverscmp</function> and return a &boolean-t;.</para>
<para>Function <function>OS:VERSION-COMPARE</function> does the same but
returns either <literal role="data">&lt;</literal>,
<literal role="data">&gt;</literal> or <literal role="data">=</literal>.
</para></section>

<section id="wildcard"><title>Wildcard Matching</title>
<para>Wildcards describe sets of file names; see <quote>&path-match;
Notation</quote> for the syntax description.</para>
<formalpara id="fnmatch-f"><title><code>(POSIX:FNMATCH &pattern-r; &string-r;
  &key-amp; :PATHNAME :PERIOD :NOESCAPE (:CASE-SENSITIVE &t;))</code></title>
<para>This function returns a non-&nil; value if the &string-r; matches
 the &pattern-r; by calling <function role="unix">fnmatch</function>.
</para></formalpara>

<formalpara id="fnmatch-matcher"><title><code>(POSIX:FNMATCH-MATCHER
   &pattern-r;)</code></title>
 <para>This function is a valid value for &apropos-matcher;.
</para></formalpara>

<note><para>These two functions used to reside in a separate package
<quote role="package">WILDCARD</quote>, which has been now deprecated.
</para></note>
</section>

<section id="mk-xterm-io"><title>XTerm</title>
<para><code>(&mk-xterm-io; &key-amp; title xterm)</code>
 When running under the &X;, you can create a &bidi-s;, which uses a new
 dedicated text window (created by the executable specified by
 the <constant>:XTERM</constant> argument which should be compatible
 with <command>xterm</command> and <command>rxvt</command>, i.e., accept
 options <option>-n</option>, <option>-T</option>, and <option>-e</option>)
 using the function &mk-xterm-io;: <programlisting language="lisp">
(&setq; &error-output-var;
      (&setq; &debug-io-var;
            (&mk-xterm-io; :title "clisp errors and debug")))
</programlisting></para><simpara>&unix-only;</simpara>
</section>

<section id="stdio"><title>Standard file input and output</title>
<para>We define the type <type>FFI:file</type> = &foreign-pointer-t; and
 the following functions:<simplelist columns="1">
  <member><code>(<function role="unix">fopen</function> &filename-r;
    &mode-r;)</code></member>
  <member><code>(<function role="unix">fdopen</function> fd
    &mode-r;)</code></member>
  <member><code>(<function role="unix">freopen</function> &filename-r;
    &mode-r; &file-r;)</code></member>
  <member><code>(<function role="unix">fclose</function>
    &file-r;)</code></member>
  <member><code>(<function role="unix">fflush</function>
    &file-r;)</code></member>
  <!-- <member><code>(<function role="unix">fgetc</function>
         &file-r;)</code></member>
       <member><code>(<function role="unix">fputc</function> int
         &file-r;)</code></member>
       <member><code>(<function role="unix">ungetc</function> int
         &file-r;)</code></member> -->
  <member><code>(<function role="unix">clearerr</function>
    &file-r;)</code></member>
  <member><code>(<function role="unix">feof</function>
    &file-r;)</code></member>
  <member><code>(<function role="unix">ferror</function>
    &file-r;)</code></member>
  <member><code>(<function role="unix">fileno</function>
    &file-r;)</code></member>
  </simplelist>call their namesakes defined in &stdio;.</para>
<para>Functions <simplelist>
   <member><function>OS:FOPEN</function></member>
   <member><function>OS:FDOPEN</function></member>
   <member><function>OS:FREOPEN</function></member>
   <member><function>OS:FCLOSE</function></member>
   <member><function>OS:FFLUSH</function></member>
   <member><function>OS:FILENO</function></member>
  </simplelist> may &signal; an &error-t;.</para>
 <variablelist><title>Return values</title>
  <varlistentry><term><function>OS:FOPEN</function></term>
   <term><function>OS:FDOPEN</function></term>
   <listitem><simpara><type>FFI:file</type> = &foreign-pointer-t;
  </simpara></listitem></varlistentry>
  <varlistentry><term><function>OS:FREOPEN</function></term>
   <term><function>OS:FCLOSE</function></term>
   <term><function>OS:FFLUSH</function></term>
   <term><function>OS:CLEARERR</function></term>
   <listitem><simpara>no values (they modify their &file-r; argument in place)
  </simpara></listitem></varlistentry>
  <varlistentry><term><function>OS:FEOF</function></term>
   <term><function>OS:FERROR</function></term>
   <listitem><simpara>&boolean-t;</simpara></listitem></varlistentry>
  <varlistentry><term><function>OS:FILENO</function></term>
   <listitem><simpara>&integer-t; (&file-des;)</simpara>
 </listitem></varlistentry></variablelist>
 <para>We also define 3 constants <simplelist columns="1">
   <member><constant>OS:STDIN</constant></member>
   <member><constant>OS:STDOUT</constant></member>
   <member><constant>OS:STDERR</constant></member>
 </simplelist></para>
<simplesect id="stdio-rationale"><title>Rationale</title>
<formalpara id="stdio-ffi"><title>Iterface to foreign libraries</title>
 <para>This functionality can be used by &ffi-pac; &module;s which
  interface to functions which use the &c-lang; <type>FILE*</type> pointers.
  E.g., &postgresql-mod; has a function <function role="pq">PQtrace</function>
  which expects a <type>FILE*</type> argument.
  You can use <function>OS:FOPEN</function>
  and <function>OS:FCLOSE</function> for that.</para></formalpara>
<formalpara id="stdio-wild"><title>Bypass &cl; filename processing</title>
 <para>You can also use this functionality to access files whose
  names are interpreted as wild by &cl;. E.g.,<programlisting language="lisp">
(&let; ((file (posix:fopen "foo*" "r")))
  (&unwind-protect;
      (&with-open-stream; (s (&make-stream; (posix:fileno file)))
        (&read-line; s))
    (posix:fclose file)))
</programlisting></para></formalpara></simplesect>
</section>

<section id="errno"><title>Error handling</title>
<para>To handle errors in foreign functions, the following four
 functions are provided: <variablelist>
<varlistentry><term><code>(POSIX:ERRNO &optional-amp; &ecode-r;)</code></term>
 <listitem><simpara>When &ecode-r; is supplied, &errno; is set (useful
   before a system call which sets &errno; as the only way to report an
   error).</simpara>
  <simpara>If &ecode-r; is a &number-t;, the corresponding &keyword-t;
   is returned and vice versa.</simpara>
  <simpara>When &ecode-r; is not supplied, the current &errno; is
   returned as a keyword if possible, a number otherwise.</simpara>
  <simpara>When &ecode-r; is &t;, all known error codes are
   returned as an &alist;.</simpara></listitem></varlistentry>
  <varlistentry><term><code>(OS:LAST-ERROR &optional-amp;
    &ecode-r;)</code></term>
  <listitem><simpara>Just like <function>POSIX:ERRNO</function>,
   but uses <function role="win32">GetLastError</function>
   and <function role="win32">SetLastError</function> instead
   of &errno;.</simpara>
  <simpara>&win32-only;</simpara></listitem></varlistentry>
<varlistentry><term><code>(POSIX:STRERROR &optional-amp;
   &ecode-r;)</code></term>
 <listitem><simpara>Return a string description of &ecode-r;.
   When &ecode-r; is not supplied, &errno; is used.</simpara>
   <simpara>This calls &strerror;.</simpara></listitem></varlistentry>
<varlistentry><term><code>(OS:FORMAT-MESSAGE &optional-amp;
   &ecode-r;)</code></term>
 <listitem><simpara>Just like <function>POSIX:STRERROR</function>,
  but uses <function role="win32">FormatMessage</function>
  and <function role="win32">GetLastError</function>.</simpara>
 <simpara>&win32-only;</simpara></listitem></varlistentry>
</variablelist></para>
</section>

<section id="misc"><title>Miscellanea</title>
<variablelist>
 <varlistentry id="clipboard"><term><code>(OS:CLIPBOARD)</code></term>
  <term><code>(&setf; (OS:CLIPBOARD) &object-r;)</code></term>
  <listitem><simpara>Get
   (using <function role="win32">GetClipboardData</function>) a set
   (using <function role="win32">SetClipboardData</function>)
   the windows clipboard.</simpara>
  <simpara>Return a &string-t;; convert &object-r; to a &string-t;
   using &princ-to-string;.</simpara>
  <simpara>&win32-cygwin-only;</simpara></listitem></varlistentry>
</variablelist></section>

</section>
