@node sb-posix
@section sb-posix
@cindex Operating System Interface
@cindex System Calls
@cindex Posix

Sb-posix is the supported interface for calling out to the operating
system.@footnote{The functionality contained in the package
@code{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
@code{opendir()} and @code{readdir()}, but not for @code{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.

Sb-posix functions do not implicitly take measures to provide thread-safety
or reentrancy beyond whatever the underlying C library does, except in
cases where doing so is necessary to maintain the consistency of the
Lisp image. For example, the bindings to the user and group database
accessing functions are neither thread-safe nor reentrant unless the
underlying libc happens to make them so (but @pxref{Extensions to
POSIX}).

@menu
* Lisp names for C names::
* Types::
* Function Parameters::
* Function Return Values::
* Lisp objects and C structures::
* Functions with idiosyncratic bindings::
* Extensions to POSIX::
@end menu


@node Lisp names for C names
@subsection  Lisp names for C names

All symbols are in the @code{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 (@code{#\_}) then replacing remaining underscore characters
with the hyphen (@code{#\-}). The requirement to uppercase is so that in
a standard upcasing reader the user may write @code{sb-posix:creat}
instead of @code{sb-posix:|creat|} as would otherise be required.

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

The user is encouraged not to @code{(USE-PACKAGE :SB-POSIX)} but instead
to use the @code{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 (@code{OPEN}, @code{CLOSE}, @code{SIGNAL} etc).

@node Types
@subsection Types

Generally, marshalling between Lisp and C data types is done using
SBCL's FFI. @xref{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, @code{rename} accepts both
pathnames and strings as its arguments.

@menu
* File-descriptors::
* Filenames::
@end menu

@node File-descriptors
@subsubsection File-descriptors

@include type-sb-posix-file-descriptor.texinfo
@include type-sb-posix-file-descriptor-designator.texinfo
@include fun-sb-posix-file-descriptor.texinfo

@node Filenames
@subsubsection Filenames

@include type-sb-posix-filename.texinfo
@include type-sb-posix-filename-designator.texinfo
@include fun-sb-posix-filename.texinfo

@node Function Parameters
@subsection Function Parameters

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

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

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

@item
Where C simulates ``out'' parameters using pointers (for instance, in
@code{pipe()} or @code{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).

@item
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.

@item
A few functions have been included in sb-posix that do not correspond
exactly with their C counterparts.  These are described in
@xref{Functions with idiosyncratic bindings}.

@end enumerate

@node Function Return Values
@subsection  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 @code{errno} on error, we instead signal an error of
type @code{SYSCALL-ERROR}.  The actual error value (@code{errno}) is
stored in this condition and can be accessed with @code{SYSCALL-ERRNO}.

We do not automatically translate the returned value into ``Lispy''
objects -- for example, @code{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.

@node Lisp objects and C structures
@subsection 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 @code{STAT} stand
in for C structures of type @code{struct stat}.

Accessors are provided for each standard field in the structure. These
are named @code{@var{structure-name}-@var{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,
@code{stat.st_dev} in C becomes @code{STAT-DEV} in Lisp.

@c This was in the README, but it proves to be false about sb-posix.
@ignore
For each Lisp object type corresponding to a C structure type, there
is a @code{make-@var{structure-name}} function that takes keyword
arguments with names deriving from each documented field name
according to the name conversion rules for accessors.
@end ignore


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.

@itemize

@item flock
@include class-sb-posix-flock.texinfo

@item passwd
@include class-sb-posix-passwd.texinfo

@item passwd
@include class-sb-posix-group.texinfo

@item stat
@include class-sb-posix-stat.texinfo

@item termios
@include class-sb-posix-termios.texinfo

@item timeval
@include class-sb-posix-timeval.texinfo
@end itemize

@node Functions with idiosyncratic bindings
@subsection Functions with idiosyncratic bindings

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

@itemize
@item getcwd
@include fun-sb-posix-getcwd.texinfo
@item readlink
@include fun-sb-posix-readlink.texinfo
@item syslog
@include fun-sb-posix-syslog.texinfo
@end itemize


@node Extensions to POSIX
@subsection Extensions to POSIX

Some of POSIX's standardized operators are not safe to use on their
own, so @code{SB-POSIX} exports a few ``helpers'' that do not
correspond exactly to functionality present in the POSIX standard.

The user and group database accessing routines are not required to be
thread-safe or reentrant, and so can only be used safely if all
clients coordinate around their use. Since it would be logically
impossible for independently developed programs to coordinate,
@code{SB-POSIX} exports two iteration macros,
@code{SB-POSIX:DO-PASSWDS} and
@code{SB-POSIX:DO-GROUPS}, each of which iterates over the respective
database while preventing the keyed accesses (@code{SB-POSIX:GETPWNAM},
@code{SB-POSIX:GETPWUID}, @code{SB-POSIX:GETGRNAM},
@code{SB-POSIX:GETGRGID})
from running until iteration completes.

@itemize
@item do-passwds
@include macro-sb-posix-do-passwds.texinfo
@item do-groups
@include macro-sb-posix-do-groups.texinfo
@end itemize
