X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=contrib%2Fsb-posix%2FREADME;h=3f61bf559171ab9311eec05162c1471d0b48030f;hb=5bf941f419b6cd275feb3ee44ca264596fbd9e8e;hp=d77b7ed80d8a27f427fa4276ea02cb1beffc89df;hpb=52632e03f75694e3780851896c3d5ec251f1f46b;p=sbcl.git

diff --git a/contrib/sb-posix/README b/contrib/sb-posix/README
index d77b7ed..3f61bf5 100644
--- a/contrib/sb-posix/README
+++ b/contrib/sb-posix/README
@@ -1,5 +1,10 @@
 -*- 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
@@ -80,14 +85,21 @@ results if the stream is buffered.
 
 A filename is a string.  
 
-A pathname is a designator for a file-descriptor: the filename is
-computed as if by NAMESTRING
+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, 
+using an FTP or HTTP client in the Lisp implementation), the effect 
+of supplying this interface with a pathname to such a file is undefined.
+
 
 ** buffer
 
-A buffer is an opaque object with accessors BUFFER-START and
-BUFFER-LENGTH, which represents an area of memory that system calls
-may access.  A buffer can be created using ALLOCATE-BUFFER or GET-BUFFER.
+A buffer is an opaque object which represents an area of memory that
+system calls may access.  It has accessors BUFFER-START and
+BUFFER-LENGTH, and can be created using ALLOCATE-BUFFER or GET-BUFFER.
 
 [ TODO: GET-BUFFER is a silly name.  Come up with a better one ]
 
@@ -159,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
-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
-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
 
@@ -184,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
-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