@c Generated by the sb-manual contrib. Do not edit.

@node sb posix
@section sb-posix

@menu
* Lisp names for C names: sb posix lisp names.
* Types: sb posix types.
* Function Parameters: sb posix function parameters.
* Function Return Values: sb posix function return values.
* Lisp Objects and C structures: sb posix lisp objects and c structures.
* Functions with Idiosyncratic Bindings: sb posix idiosyncracies.
* Extensions to POSIX: sb posix extensions to posix.
@end menu

Sb-posix is the supported interface for calling out to the operating
system.

@quotation
@emph{Note}: 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.
@end quotation

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(3)} and @code{readdir(3)} but not for @code{printf(3)}. 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
see @ref{sb posix extensions to posix}).

@node sb posix lisp 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 @code{sb-posix} package have the same
name as CL symbols (e.g. @code{open}, @code{close}, @code{signal}). Also, see
@ref{package local nicknames}.

@node sb posix types
@subsection Types

@menu
* File-descriptors: sb posix file descriptors.
* Filenames: sb posix filenames.
@end menu

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

@node sb posix file descriptors
@subsubsection File-descriptors

@anchor{Type sb-posix file-descriptor}
@ttindex @sortas{file-descriptor sb-posix} file-descriptor [sb-posix]
@deffn{Type} sb-posix:file-descriptor
A @code{fixnum} designating a native file descriptor.

@code{sb-sys:make-fd-stream} can be used to construct a @code{file-stream} associated with a
native file descriptor.

Note that mixing I/O operations on a @code{file-stream} with operations directly on its
descriptor may produce unexpected results if the stream is buffered.
@end deffn
@anchor{Type sb-posix file-descriptor-designator}
@ttindex @sortas{file-descriptor-designator sb-posix} file-descriptor-designator [sb-posix]
@deffn{Type} sb-posix:file-descriptor-designator
Designator for a @code{file-descriptor}: either a fixnum designating
itself, or a @code{file-stream} designating the underlying file-descriptor.
@end deffn
@anchor{Function sb-posix file-descriptor}
@ffindex @sortas{file-descriptor sb-posix} file-descriptor [sb-posix]
@deffn{Function} sb-posix:file-descriptor file-descriptor
Converts @code{file-descriptor-designator} into a @code{file-descriptor}.
@end deffn
@node sb posix filenames
@subsubsection Filenames

@anchor{Type sb-posix filename}
@ttindex @sortas{filename sb-posix} filename [sb-posix]
@deffn{Type} sb-posix:filename
A @code{string} designating a filename in native namestring syntax.

Note that native namestring syntax is distinct from Lisp namestring syntax:

@example
(pathname "/foo*/bar")
@end example

is a wild pathname with a pattern-matching directory component.
@code{sb-ext:parse-native-namestring} may be used to construct Lisp pathnames that
denote POSIX filenames as understood by system calls, and
@code{sb-ext:native-namestring} can be used to coerce them into strings in the native
namestring syntax.

Note also that POSIX filename syntax does not distinguish the names of files
from the names of directories: in order to parse the name of a directory in
POSIX filename syntax into a pathname @code{my-defaults} for which

@example
(merge-pathnames (make-pathname :name "FOO" :case :common)
                  my-defaults)
@end example

returns a pathname that denotes a file in the directory, supply a true
@code{:as-directory} argument to @code{sb-ext:parse-native-namestring}. Likewise, to supply
the name of a directory to a POSIX function in non-directory syntax, supply a
true @code{:as-file} argument to @code{sb-ext:native-namestring}.
@end deffn
@anchor{Type sb-posix filename-designator}
@ttindex @sortas{filename-designator sb-posix} filename-designator [sb-posix]
@deffn{Type} sb-posix:filename-designator
Designator for a @code{filename}: a @code{string} designating itself, or a
designator for a @code{pathname} designating the corresponding native namestring.
@end deffn
@anchor{Function sb-posix filename}
@ffindex @sortas{filename sb-posix} filename [sb-posix]
@deffn{Function} sb-posix:filename filename
Converts @code{filename-designator} into a @code{filename}.
@end deffn
@node sb posix 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:

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

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

@item Where C simulates "out" parameters using pointers (for instance,
  in @code{pipe(2)} or @code{socketpair(2)}), 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 @ref{sb posix 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 @ref{sb posix idiosyncracies}.
@end itemize

@node sb posix 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{sb-posix:syscall-error}. The actual error
value (@code{errno}) is stored in this condition and can be accessed with
@code{sb-posix: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 sb posix 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{sb-posix: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{<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,
@code{stat.st_dev} in C becomes @code{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.

@anchor{Class sb-posix flock}
@ttindex @sortas{flock sb-posix} flock [sb-posix]
@deffn{Class} sb-posix:flock
Class representing locks used in @code{fcntl(2)}.
@end deffn
@anchor{Class sb-posix passwd}
@ttindex @sortas{passwd sb-posix} passwd [sb-posix]
@deffn{Class} sb-posix:passwd
Instances of this class represent entries in the system's user database.
@end deffn
@anchor{Class sb-posix group}
@ttindex @sortas{group sb-posix} group [sb-posix]
@deffn{Class} sb-posix:group
Instances of this class represent entries in the system's group database.
@end deffn
@anchor{Class sb-posix stat}
@ttindex @sortas{stat sb-posix} stat [sb-posix]
@deffn{Class} sb-posix:stat
Instances of this class represent POSIX file metadata.
@end deffn
@anchor{Class sb-posix termios}
@ttindex @sortas{termios sb-posix} termios [sb-posix]
@deffn{Class} sb-posix:termios
Instances of this class represent I/O characteristics of the terminal.
@end deffn
@anchor{Class sb-posix timeval}
@ttindex @sortas{timeval sb-posix} timeval [sb-posix]
@deffn{Class} sb-posix:timeval
Instances of this class represent time values.
@end deffn
@node sb posix idiosyncracies
@subsection Functions with Idiosyncratic Bindings

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

@anchor{Function sb-posix getcwd}
@ffindex @sortas{getcwd sb-posix} getcwd [sb-posix]
@deffn{Function} sb-posix:getcwd
Returns the process's current working directory as a string.
@end deffn
@anchor{Function sb-posix readlink}
@ffindex @sortas{readlink sb-posix} readlink [sb-posix]
@deffn{Function} sb-posix:readlink pathspec
Returns the resolved target of a symbolic link as a string.
@end deffn
@anchor{Function sb-posix syslog}
@ffindex @sortas{syslog sb-posix} syslog [sb-posix]
@deffn{Function} sb-posix:syslog priority format &rest args
Send a message to the syslog facility, with severity level
@code{priority}.  The message will be formatted as by @code{cl:format} (rather
than C's @code{printf}) with format string @code{format} and arguments @code{args}.
@end deffn
@node sb posix 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.

@anchor{Macro sb-posix do-passwds}
@ffindex @sortas{do-passwds sb-posix} do-passwds [sb-posix]
@deffn{Macro} sb-posix:do-passwds (passwd &optional result) &body body
Evaluate @code{body} with @code{passwd} bound to successive entries from the passwd
database, and return @code{result}. An implicit block named @code{nil} surrounds
the form; an implicit @code{tagbody} surrounds @code{body}. It is unspecified
whether @code{passwd} is assigned, rebound, or destructively modified upon
each iteration. It is an error to use any operator that accesses the
@code{passwd} database during the dynamic extent of @code{do-passwds}.
@end deffn
@anchor{Macro sb-posix do-groups}
@ffindex @sortas{do-groups sb-posix} do-groups [sb-posix]
@deffn{Macro} sb-posix:do-groups (group &optional result) &body body
Evaluate @code{body} with @code{group} bound to successive entries from the group
database, and return @code{result}. An implicit block named @code{nil} surrounds
the form; an implicit @code{tagbody} surrounds @code{body}. It is unspecified
whether @code{group} is assigned, rebound, or destructively modified upon
each iteration. It is an error to use any operator that accesses the
@code{group} database during the dynamic extent of @code{do-groups}.
@end deffn
