-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 flock
+@include class-sb-posix-flock.texinfo
+
+@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