sb-posix
========

Sb-posix is the supported interface for calling out to the operating system. (The functionality contained in the package SB-UNIX is for SBCL internal use only; its contents are likely to change from version to version.)

The scope of this interface is ``operating system calls on a typical Unixlike platform''.  This is section 2 of the Unix manual, plus section 3 calls that are (a) typically found in libc, but (b) not part of the C standard.  For example, we intend to provide support for opendir() and readdir(), but not for printf(). That said, if your favourite system call is not included yet, you are encouraged to submit a patch to the SBCL mailing list.

Some facilities are omitted where they offer absolutely no additional use over some portable function, or would be actively dangerous to the consistency of Lisp.  Not all functions are available on all platforms.

Lisp names for C names
----------------------

All symbols are in the SB-POSIX package.  This package contains a Lisp function for each supported Unix system call or function, a variable or constant for each supported Unix constant, an object type for each supported Unix structure type, and a slot name for each supported Unix structure member.  A symbol name is derived from the C binding's name, by (a) uppercasing, then (b) removing leading underscores (#\_) then replacing remaining underscore characters with the hyphen (#\-). The requirement to uppercase is so that in a standard upcasing reader the user may write sb-posix:creat instead of sb-posix:|creat| as would otherise be required.

No other changes to ``Lispify'' symbol names are made, so creat() becomes CREAT, not CREATE.

The user is encouraged not to (USE-PACKAGE :SB-POSIX) but instead to use the SB-POSIX: prefix on all references, as some of the symbols symbols contained in the SB-POSIX package have the same name as CL symbols (OPEN, CLOSE, SIGNAL etc).

Types
-----

Generally, marshalling between Lisp and C data types is done using SBCL's FFI. See Foreign Function Interface.

Some functions accept objects such as filenames or file descriptors.  In the C binding to POSIX these are represented as strings and small integers respectively. For the Lisp programmer's convenience we introduce designators such that CL pathnames or open streams can be passed to these functions.  For example, rename accepts both pathnames and strings as its arguments.

File-descriptors
................

A file-descriptor is a non-negative small integer.

A file-stream is a designator for a file-descriptor: the stream's file descriptor is extracted.  Note that mixing I/O operations on a stream with operations directly on its descriptor may produce unexpected results if the stream is buffered.

SB-EXT:MAKE-FD-STREAM can be used to construct a stream associated with a file descriptor.

Filenames
.........

A filename is a string.

A pathname is a designator for a filename: the filename is computed using the same mechanism that SBCL uses to map pathnames to OS filenames internally.

Note that filename syntax is distinct from namestring syntax, and that SB-EXT:PARSE-NATIVE-NAMESTRING may be used to construct Lisp pathnames that denote POSIX filenames returned by system calls. See Function sb-ext:parse-native-namestring.  Additionally, notice that POSIX filename syntax does not distinguish the names of files from the names of directories.  Consequently, in order to parse the name of a directory in POSIX filename syntax into a pathname defaults for which

     (merge-pathnames (make-pathname :name "FOO" :case :common)
                      defaults)

returns a pathname that denotes a file in the directory, supply a true AS-DIRECTORY argument to SB-EXT:PARSE-NATIVE-NAMESTRING. Likewise, if it is necessary to supply the name of a directory to a POSIX function in non-directory syntax, supply a true AS-FILE argument to SB-EXT:NATIVE-NAMESTRING.

Type conversion functions
.........................

For each of these types there is a function of the same name that converts any valid designator for the type into an object of said type.

     (with-open-file (o "/tmp/foo" :direction :output)
       (sb-posix:file-descriptor o))
     => 4

Function Parameters
-------------------

The calling convention is modelled after that of CMUCL's UNIX package: in particular, it's like the C interface except that:

 a. Length arguments are omitted or optional where the sensible value is obvious.  For example, read would be defined this way:

          (read fd buffer &optional (length (length buffer))) => bytes-read

 b. Where C simulates ``out'' parameters using pointers (for instance, in pipe() or socketpair()) these may be optional or omitted in the Lisp interface: if not provided, appropriate objects will be allocated and returned (using multiple return values if necessary).

 c. Some functions accept objects such as filenames or file descriptors. Wherever these are specified as such in the C bindings, the Lisp interface accepts designators for them as specified in the 'Types' section above.

 d. A few functions have been included in sb-posix that do not correspond exactly with their C counterparts.  These are described in see Functions with idiosyncratic bindings.

Function Return Values
----------------------

The return value is usually the same as for the C binding, except in error cases: where the C function is defined as returning some sentinel value and setting errno on error, we instead signal an error of type SYSCALL-ERROR.  The actual error value (errno) is stored in this condition and can be accessed with SYSCALL-ERRNO.

We do not automatically translate the returned value into ``Lispy'' objects -- for example, SB-POSIX:OPEN returns a small integer, not a stream.  Exception: boolean-returning functions (or, more commonly, macros) do not return a C integer, but instead a Lisp boolean.

Lisp objects and C structures
-----------------------------

Sb-posix provides various Lisp object types to stand in for C structures in the POSIX library.  Lisp bindings to C functions that accept, manipulate, or return C structures accept, manipulate, or return instances of these Lisp types instead of instances of alien types.

The names of the Lisp types are chosen according to the general rules described above.  For example Lisp objects of type STAT stand in for C structures of type struct stat.

Accessors are provided for each standard field in the structure. These are named STRUCTURE-NAME-FIELD-NAME where the two components are chosen according to the general name conversion rules, with the exception that in cases where all fields in a given structure have a common prefix, that prefix is omitted. For example, stat.st_dev in C becomes STAT-DEV in Lisp.

Because sb-posix might not support all semi-standard or implementation-dependent members of all structure types on your system (patches welcome), here is an enumeration of all supported Lisp objects corresponding to supported POSIX structures, and the supported slots for those structures.

  * flock
          [file class-sb-posix-flock.texinfo not included]

  * passwd
          [file class-sb-posix-passwd.texinfo not included]

  * stat
          [file class-sb-posix-stat.texinfo not included]

  * termios
          [file class-sb-posix-termios.texinfo not included]

  * timeval
          [file class-sb-posix-timeval.texinfo not included]

Functions with idiosyncratic bindings
-------------------------------------

A few functions in sb-posix don't correspond directly to their C counterparts.

  * getcwd
          [file fun-sb-posix-getcwd.texinfo not included]

  * readlink
          [file fun-sb-posix-readlink.texinfo not included]

  * syslog
          [file fun-sb-posix-syslog.texinfo not included]