(let ((to-protocol (intern (format nil "ALIEN-TO-~A" name)))
(to-alien (intern (format nil "~A-TO-ALIEN" name))))
`(progn
+ (export ',name :sb-posix)
(defclass ,name ,superclasses
,(loop for slotd in slots
collect (ldiff slotd (member :array-length slotd)))
(progn
(export 'readlink :sb-posix)
(defun readlink (pathspec)
+ "Returns the resolved target of a symbolic link as a string."
(flet ((%readlink (path buf length)
(alien-funcall
(extern-alien "readlink" (function int c-string (* t) int))
(progn
(export 'getcwd :sb-posix)
(defun getcwd ()
+ "Returns the process's current working directory as a string."
(flet ((%getcwd (buffer size)
(alien-funcall
(extern-alien #-win32 "getcwd"
(export (defun getpagesize () 4096))
;;; passwd database
+;; The docstrings are copied from the descriptions in SUSv3,
+;; where present.
#-win32
(define-protocol-class passwd alien-passwd ()
- ((name :initarg :name :accessor passwd-name)
- (passwd :initarg :passwd :accessor passwd-passwd)
- (uid :initarg :uid :accessor passwd-uid)
- (gid :initarg :gid :accessor passwd-gid)
- (gecos :initarg :gecos :accessor passwd-gecos)
- (dir :initarg :dir :accessor passwd-dir)
- (shell :initarg :shell :accessor passwd-shell)))
+ ((name :initarg :name :accessor passwd-name
+ :documentation "User's login name.")
+ ;; Note: SUSv3 doesn't require this member.
+ (passwd :initarg :passwd :accessor passwd-passwd
+ :documentation "The account's encrypted password.")
+ (uid :initarg :uid :accessor passwd-uid
+ :documentation "Numerical user ID.")
+ (gid :initarg :gid :accessor passwd-gid
+ :documentation "Numerical group ID.")
+ ;; Note: SUSv3 doesn't require this member.
+ (gecos :initarg :gecos :accessor passwd-gecos
+ :documentation "User's name or comment field.")
+ (dir :initarg :dir :accessor passwd-dir
+ :documentation "Initial working directory.")
+ (shell :initarg :shell :accessor passwd-shell
+ :documentation "Program to use as shell."))
+ (:documentation "Instances of this class represent entries in
+ the system's user database."))
(defmacro define-pw-call (name arg type)
#-win32
#-win32
(define-protocol-class timeval alien-timeval ()
- ((sec :initarg :tv-sec :accessor timeval-sec)
- (usec :initarg :tv-usec :accessor timeval-usec)))
+ ((sec :initarg :tv-sec :accessor timeval-sec
+ :documentation "Seconds.")
+ (usec :initarg :tv-usec :accessor timeval-usec
+ :documentation "Microseconds."))
+ (:documentation "Instances of this class represent time values."))
(define-protocol-class stat alien-stat ()
- ((mode :initarg :mode :accessor stat-mode)
- (ino :initarg :ino :accessor stat-ino)
- (dev :initarg :dev :accessor stat-dev)
- (nlink :initarg :nlink :accessor stat-nlink)
- (uid :initarg :uid :accessor stat-uid)
- (gid :initarg :gid :accessor stat-gid)
- (size :initarg :size :accessor stat-size)
- (atime :initarg :atime :accessor stat-atime)
- (mtime :initarg :mtime :accessor stat-mtime)
- (ctime :initarg :ctime :accessor stat-ctime)))
+ ((mode :initarg :mode :reader stat-mode
+ :documentation "Mode of file.")
+ (ino :initarg :ino :reader stat-ino
+ :documentation "File serial number.")
+ (dev :initarg :dev :reader stat-dev
+ :documentation "Device ID of device containing file.")
+ (nlink :initarg :nlink :reader stat-nlink
+ :documentation "Number of hard links to the file.")
+ (uid :initarg :uid :reader stat-uid
+ :documentation "User ID of file.")
+ (gid :initarg :gid :reader stat-gid
+ :documentation "Group ID of file.")
+ (size :initarg :size :reader stat-size
+ :documentation "For regular files, the file size in
+ bytes. For symbolic links, the length
+ in bytes of the filename contained in
+ the symbolic link.")
+ (atime :initarg :atime :reader stat-atime
+ :documentation "Time of last access.")
+ (mtime :initarg :mtime :reader stat-mtime
+ :documentation "Time of last data modification.")
+ (ctime :initarg :ctime :reader stat-ctime
+ :documentation "Time of last status change"))
+ (:documentation "Instances of this class represent Posix file
+ metadata."))
(defmacro define-stat-call (name arg designator-fun type)
;; FIXME: this isn't the documented way of doing this, surely?
(export ',lisp-name :sb-posix)
(declaim (inline ,lisp-name))
(defun ,lisp-name (,arg &optional stat)
- (declare (type (or null (sb-alien:alien (* alien-stat))) stat))
+ (declare (type (or null stat) stat))
(with-alien-stat a-stat ()
(let ((r (alien-funcall
(extern-alien ,(real-c-name (list name :options :largefile)) ,type)
#-win32
(define-protocol-class termios alien-termios ()
- ((iflag :initarg :iflag :accessor sb-posix:termios-iflag)
- (oflag :initarg :oflag :accessor sb-posix:termios-oflag)
- (cflag :initarg :cflag :accessor sb-posix:termios-cflag)
- (lflag :initarg :lflag :accessor sb-posix:termios-lflag)
- (cc :initarg :cc :accessor sb-posix:termios-cc :array-length nccs)))
+ ((iflag :initarg :iflag :accessor sb-posix:termios-iflag
+ :documentation "Input modes.")
+ (oflag :initarg :oflag :accessor sb-posix:termios-oflag
+ :documentation "Output modes.")
+ (cflag :initarg :cflag :accessor sb-posix:termios-cflag
+ :documentation "Control modes.")
+ (lflag :initarg :lflag :accessor sb-posix:termios-lflag
+ :documentation "Local modes.")
+ (cc :initarg :cc :accessor sb-posix:termios-cc :array-length nccs
+ :documentation "Control characters"))
+ (:documentation "Instances of this class represent I/O
+ characteristics of the terminal."))
#-win32
(progn
@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
+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()}.
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. [TBD: unavailable functions should (a) not exist, or (b)
-exist but signal some kind of "not available on this platform" error]
+platforms.
-The general intent is for a low-level interface. There are three
-reasons for this: it's easier to write a high-level interface given a
-low-level one than vice versa, there are fewer philosophical
-disagreements about what it should look like, and the work of
-implementing it is easily parallelisable - and in fact, can be
-attempted on an as-needed basis by the various people who want it.
+@menu
+* Lisp names for C names::
+* Types::
+* Lisp objects and C structures::
+* Function Parameters::
+* Function Return Values::
+* Functions with idiosyncratic bindings::
+@end menu
-@subsection Lisp names for system calls
+
+@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, and a
-variable or constant for each supported Unix constant. 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{posix:creat} instead of @code{posix:|creat|} as would otherise be
-required.
-
-No other changes to "Lispify" symbol names are made, so @code{creat()}
+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 our
-symbols have the same name as CL symbols (@code{OPEN}, @code{CLOSE},
-@code{SIGNAL} etc).
-
-@quotation
-Rationale: We use similar names to the C bindings so that unix manual
-pages can be used for documentation. To avoid name clashes with CL or
-other functions, the approaches considered were (a) prefix the names of
-clashing symbols with "POSIX-" or similar, (b) prefix @emph{all} symbols with
-"POSIX-", (c) use the packaging system to resolve ambiguities. (a) was
-rejected as the set of symbols we may potentially clash with is not
-fixed (for example, if new symbols are added to @code{SB-EXT}) so
-symbols might have to be renamed over the lifetime of SB-POSIX, which is
-not good. The choice between (b) and (c) was made on the grounds that
-@code{POSIX-OPEN} is about as much typing as @code{SB-POSIX:OPEN}
-anyway, and symbol munging is, the author feels, slightly tacky, when
-there's a package system available to do it more cleanly.
-@end quotation
+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.
+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::
+* Type conversion functions::
+@end menu
+@node File-descriptors
@subsubsection 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 io operations on a stream
+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.
+@code{SB-EXT:MAKE-FD-STREAM} can be used to construct a stream
+associated with a file descriptor.
+
+@node Filenames
@subsubsection Filenames
A filename is a string.
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
+@code{SB-EXT:PARSE-NATIVE-NAMESTRING} may be used to construct
+Lisp pathnames that denote POSIX filenames returned by system calls.
+@xref{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
+@code{defaults} for which
+
+@lisp
+(merge-pathnames (make-pathname :name "FOO" :case :common)
+ defaults)
+@end lisp
+
+@noindent
+returns a pathname that denotes a file in the directory, it's necessary
+to append a forward slash to the POSIX filename. Otherwise, the last
+directory name will be parsed as a filename.
+
+@node Type conversion functions
@subsubsection Type conversion functions
For each of these types there is a function of the same name that
=> 4
@end lisp
-@subsection Function parameters
+@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:
@end lisp
@item
-Where C simulates "out" parameters using pointers (for instance, in
+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).
Wherever these are specified as such in the C bindings, the Lisp
interface accepts designators for them as specified in the 'Types'
section above.
-@end enumerate
-@quotation
-Rationale: Keeping exact 1:1 correspondence with C conventions is less
-important here, as the function argument list can easily be accessed to
-find out exactly what the arguments are. Designators are primarily a
-convenience feature.
-@end quotation
+@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
-@subsection Function return values
+@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}.
-[TBD: some interface to @code{strerror}, to get the user-readable
-translation of the error number]
-We do not automatically translate the returned value into "Lispy"
+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
-[ or maybe "true"/"false" in CLtS parlance ]; the rationale behind this
-exception is that there is nothing that can be meaningfully done with
-the boolean except test for truth or falsity -- it cannot be passed
-meaningfully to other POSIX functions.
-
-@quotation
-Rationale: This is an interface to POSIX, not a high-level interface
-that uses POSIX, and many people using it will actually want to mess
-with the file descriptors directly. People needing Lispy interfaces can
-implement them atop this - or indeed, use the existing COMMON-LISP
-package, which already has many high-level constructs built on top of
-the operating system ;-)
-@end quotation
-
+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 passwd
+@include class-sb-posix-passwd.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
projects / sbcl.git / commitdiff