upgrade asdf to 2.29, per request by Faré (sbcl-devel 2013-02-16)

[sbcl.git] / contrib / sb-posix / README

diff --git a/contrib/sb-posix/README b/contrib/sb-posix/README
index 5448ffe..3f61bf5 100644 (file)
--- a/contrib/sb-posix/README
+++ b/contrib/sb-posix/README
@@ -1,5 +1,10 @@
 -*- Text -*-
 
 -*- Text -*-
 

+Note: this file's description of a POSIX binding for Common Lisp does
+not necessarily describe the state of the sb-posix module.  If you're
+looking for a description sb-posix, look at sb-posix.texinfo in this
+directory.
+

 * Scope
 
 The scope of this interface is "operating system calls on a typical
 * Scope
 
 The scope of this interface is "operating system calls on a typical

@@ -80,9 +85,9 @@ results if the stream is buffered.
 
 A filename is a string.  
 
 
 A filename is a string.  
 

-A pathname is a designator for a file-descriptor: the filename is
-computed using the same mechanism as the implementation would
-use to map pathnames to OS filenames internally.
+A pathname is a designator for a filename: the filename is computed
+using the same mechanism as the implementation would use to map
+pathnames to OS filenames internally.

 
 In an implementation that supports pathnames to files on other hosts, 
 using mechanisms not available to the underlying OS (for example, 
 
 In an implementation that supports pathnames to files on other hosts, 
 using mechanisms not available to the underlying OS (for example, 

@@ -166,11 +171,12 @@ is obvious.  For example,
 (read fd buffer &optional (length (length buffer))) => bytes-read
 
 b) where C simulates "out" parameters using pointers (for instance, in
 (read fd buffer &optional (length (length buffer))) => bytes-read
 
 b) where C simulates "out" parameters using pointers (for instance, in

-pipe() or socketpair()) we may use multiple return values instead.
-This doesn't apply to data transfer functions that fill buffers.
+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
 
 c) some functions accept objects such as filenames or file

-descriptors.  Wherver these are specified as such in the C bindings,
+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
 
 the Lisp interface accepts designators for them as specified in the
 'Types' section above
 

@@ -191,7 +197,12 @@ of the error number]
 
 We do not automatically translate the returned value into "Lispy"
 objects - for example, SB-POSIX:OPEN returns a small integer, not a
 
 We do not automatically translate the returned value into "Lispy"
 objects - for example, SB-POSIX:OPEN returns a small integer, not a

-stream.
+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.

 
 [ 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
 
 [ 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