<?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>.</para>

<variablelist>
 <varlistentry><term><literal
    role="sexp">(<function>POSIX:RESOLVE-HOST-IPADDR</function>
    &optional-amp; &host-r;)</literal></term>
 <listitem><simpara>Returns the <type>HOSTENT</type> structure (name,
   list of aliases, list of IP addresses as dotted quads (for IPv4) or
   coloned octets (for IPv6), address type - IPv4 or IPv6).
   When &host-r; is omitted or &default-k;, return the data for the
   current host. When &host-r; is given and 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).
   This is an interface to &gethostbyname;/&gethostbyaddr;.
  </simpara></listitem></varlistentry>
 <varlistentry id="file-stat"><term><literal
      role="sexp">(<function>POSIX:FILE-STAT</function> &path-r;
      &optional-amp; <replaceable>link-p</replaceable>)</literal></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 &stat;/&fstat;/&lstat; was called.
   The other slots are numbers, members of the <type>struct stat</type>:
    <variablelist>
     <varlistentry><term>dev</term>
      <listitem><simpara>Device ID of device containing file.
     </simpara></listitem></varlistentry>
     <varlistentry><term>ino</term>
      <listitem><simpara>File serial number.
     </simpara></listitem></varlistentry>
     <varlistentry><term>mode</term>
      <listitem><simpara>Mode of file.
     </simpara></listitem></varlistentry>
     <varlistentry><term>nlink</term>
      <listitem><simpara>Number of hard links to the file.
     </simpara></listitem></varlistentry>
     <varlistentry><term>uid</term>
      <listitem><simpara>User ID of file.
     </simpara></listitem></varlistentry>
     <varlistentry><term>gid</term>
      <listitem><simpara>Group ID of file.
     </simpara></listitem></varlistentry>
     <varlistentry><term>rdev</term>
      <listitem><simpara>Device ID (if file is character or block
        special).</simpara></listitem></varlistentry>
     <varlistentry><term>size</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>atime</term>
      <listitem><simpara>Time of last access (as the number of seconds
        since 1900-01-01).</simpara></listitem></varlistentry>
     <varlistentry><term>mtime</term>
      <listitem><simpara>Time of last data modification (as the number of
        seconds since 1900-01-01).</simpara></listitem></varlistentry>
     <varlistentry><term>ctime</term>
      <listitem><simpara>Time of last status change (as the number of
        seconds since 1900-01-01).</simpara></listitem></varlistentry>
     <varlistentry><term>blksize</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>blocks</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><simpara>[&unix; systems only at this time, patches are welcome.]
 </simpara></listitem></varlistentry>
 <varlistentry id="stat-vfs"><term><literal
      role="sexp">(<function>POSIX:STAT-VFS</function>
    &path-r;)</literal></term>
 <listitem><para>Return the <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 &statvfs;/&fstatvfs; was called.
   The other slots are members of the <type>struct statvfs</type>:
   <variablelist>
    <varlistentry><term>bsize</term>
     <listitem><simpara>File system block size.
    </simpara></listitem></varlistentry>
    <varlistentry><term>frsize</term>
     <listitem><simpara>Fundamental file system block size.
    </simpara></listitem></varlistentry>
    <varlistentry><term>blocks</term>
     <listitem><simpara>Total number of blocks on file system in units
       of <literal>frsize</literal>.</simpara></listitem></varlistentry>
    <varlistentry><term>bfree</term>
     <listitem><simpara>Total number of free blocks.
    </simpara></listitem></varlistentry>
    <varlistentry><term>bavail</term>
     <listitem><simpara>Number of free blocks available to
       non-privileged processes.</simpara></listitem></varlistentry>
    <varlistentry><term>files</term>
     <listitem><simpara>Total number of file serial numbers.
    </simpara></listitem></varlistentry>
    <varlistentry><term>ffree</term>
     <listitem><simpara>Total number of free file serial numbers.
    </simpara></listitem></varlistentry>
    <varlistentry><term>favail</term>
     <listitem><simpara>Number of file serial numbers available to
       non-privileged processes.</simpara></listitem></varlistentry>
    <varlistentry><term>fsid</term>
     <listitem><simpara>File system ID.</simpara></listitem></varlistentry>
    <varlistentry><term>flag</term>
     <listitem><simpara>List of platform-dependent values, such as &ro-k;.
    </simpara></listitem></varlistentry>
    <varlistentry><term>namemax</term>
     <listitem><simpara>Maximum filename length.
   </simpara></listitem></varlistentry></variablelist>
   All slots are read-only.
  </para><simpara>[&unix; systems only at this time, patches are welcome.]
 </simpara></listitem></varlistentry>
 <varlistentry id="file-info"><term><literal
    role="sexp">(<function>OS:FILE-INFO</function>
    &path-r;)</literal></term>
 <listitem><simpara>Return the <type>FILE-INFO</type> structure.
   &path-r; should be a &path-des;. The 8 slots are attributes, ctime,
   atime, wtime, high and low sizes, name and short name.
   </simpara><simpara>[&win32; systems only at this time, patches are welcome.]
  </simpara></listitem></varlistentry>
 <varlistentry><term><literal
    role="sexp">(<function>POSIX:USER-DATA</function>
    &optional-amp; <replaceable>user</replaceable>)</literal></term>
 <listitem><simpara>Return the <type>PASSWD</type> structure (name,
   encoded password, UID, GID, full name, home directory, shell).
   When <replaceable>user</replaceable> is &nil;, return all users.
   When <replaceable>user</replaceable> is &default-k; or
   not supplied, return the information about the current user.
   If the system does not support a particular field (e.g., Win32 does
   not have a concept of a shell), &nil; (or the default, like
   <filename>c:\command.com</filename> for DOS) is returned.
   </simpara><simpara>[&unix; systems only at this time, patches are welcome.]
  </simpara></listitem></varlistentry>
 <varlistentry><term><literal
   role="sexp">(<function>POSIX:UNAME</function>)</literal></term>
  <listitem><simpara>Return a structure describing the OS, derived from
    &uname;.</simpara></listitem></varlistentry>
 <varlistentry><term><literal
   role="sexp">(<function>POSIX:SYSCONF</function>)</literal></term>
  <listitem><simpara>Return a structure describing the system
    configuration, derived from &sysconf;.</simpara></listitem></varlistentry>
 <varlistentry><term><literal
   role="sexp">(<function>POSIX:LIMITS</function>)</literal></term>
  <listitem><simpara>Return a structure describing the resource limits,
    derived from &getrlimit;.</simpara></listitem></varlistentry>
 <varlistentry><term><literal
   role="sexp">(<function>POSIX:USAGE</function>)</literal></term>
  <listitem><simpara>Return 2 structures describing the resource usage by
    the lisp process its children, derived from &getrusage;.
  </simpara></listitem></varlistentry>
 <varlistentry>
   <term><literal role="sexp">(<function>POSIX:ERF</function>
       &real-r;)</literal></term>
   <term><literal role="sexp">(<function>POSIX:ERFC</function>
       &real-r;)</literal></term>
   <term><literal role="sexp">(<function>POSIX:J0</function>
       &real-r;)</literal></term>
   <term><literal role="sexp">(<function>POSIX:J1</function>
       &real-r;)</literal></term>
   <term><literal role="sexp">(<function>POSIX:JN</function>
       &int-r; &real-r;)</literal></term>
   <term><literal role="sexp">(<function>POSIX:Y0</function>
       &real-r;)</literal></term>
   <term><literal role="sexp">(<function>POSIX:Y1</function>
       &real-r;)</literal></term>
   <term><literal role="sexp">(<function>POSIX:YN</function>
       &int-r; &real-r;)</literal></term>
   <term><literal role="sexp">(<function>POSIX:GAMMA</function>
       &real-r;)</literal></term>
   <term><literal role="sexp">(<function>POSIX:LGAMMA</function>
       &real-r;)</literal></term>
 <listitem><simpara>Compute the error functions, Bessel functions and
   Gamma.  These functions are required by the POSIX standard and should
   be available in libm.so.  Please note that these functions do not
   provide lisp-style error handling and precision, and do all the
   computations at the double float level.
 </simpara></listitem></varlistentry>
 <varlistentry id="stream-lock"><term>
   <literal role="sexp">(<function>POSIX:STREAM-LOCK</function> &stream-r;
    <replaceable>lock-p</replaceable> &key-amp;
    (:BLOCK &t;) (:SHARED &nil;) (:START 0) (:END &nil;))</literal></term>
  <listitem><simpara>This is an interface to the &fcntl; system call.
   It sets or removes 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 the file is already locked, it &signal;s an &error-t;.
   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 <emphasis>exclusive</emphasis> (i.e., <emphasis>write</emphasis>,
   or non-<replaceable>shared</replaceable>) lock.
 </simpara></listitem></varlistentry>
 <varlistentry><term>
   <literal role="sexp">(<function>POSIX:COPY-FILE</function>
    <replaceable>source-path</replaceable>
    <replaceable>destination-path</replaceable>
    &key-amp; :METHOD :PRESERVE :IF-EXISTS :IF-DOES-NOT-EXIST)</literal></term>
  <listitem><simpara>This is an interface to the &symlink;
    (when <replaceable>method</replaceable> is <constant>:SYMLINK</constant>),
    &link; (when it is <constant>:HARDLINK</constant>), and &rename;
    (when it is <constant>:RENAME</constant>) system calls, as well as,
    you guessed it, a generic file copy utility
    (when <replaceable>method</replaceable> is &copy-k;).
   </simpara><simpara>Both <replaceable>source-path</replaceable> and
    <replaceable>destination-path</replaceable> may be wild.
 </simpara></listitem></varlistentry>
 <varlistentry><term>
   <literal role="sexp">(<function>POSIX:DUPLICATE-HANDLE</function>
    <replaceable>fd1</replaceable>
    &optional-amp; <replaceable>fd2</replaceable>)</literal></term>
  <listitem><simpara>This is an interface to the &dup; system calls on
   &unix; systems and to <function>DuplicateHandle</function> system
   call on &win32;.</simpara></listitem></varlistentry>
 <varlistentry><term><literal role="sexp">(OS:SHORTCUT-INFO
    &path-r;)</literal></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><term><literal role="sexp">(OS:MAKE-SHORTCUT
    &path-r; &key-amp; :WORKING-DIRECTORY :ARGUMENTS :SHOW-COMMAND :ICON
    :DESCRIPTION :HOT-KEY :PATH)</literal></term>
  <listitem><simpara>Create (or modify the properties of an existing one)
    a &win32; shortcut (<filename>#P".lnk"</filename>) file.
 </simpara></listitem></varlistentry>
 <varlistentry><term><literal role="sexp">(OS:SYSTEM-INFO)</literal></term>
  <listitem><simpara>Return &win32; system information in a
    <type>SYSTEM-INFO</type> structure.</simpara></listitem></varlistentry>
 <varlistentry><term><literal role="sexp">(OS:VERSION)</literal></term>
  <listitem><simpara>Return &win32; version information in a
    <type>SYSTEM-INFO</type> structure.</simpara></listitem></varlistentry>
</variablelist>

</section>
