X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=contrib%2Fsb-posix%2Fmacros.lisp;h=e9ec78b478fd36aba5338c7148a30da7a3e4cac6;hb=7c75cd363da90afe334e936aad2b63437ea5905d;hp=f80e714c419c9656e5ad5eeffe209773e481b6f1;hpb=f7e3e709f7c2207f1923375942f7fb1c092f92b0;p=sbcl.git

diff --git a/contrib/sb-posix/macros.lisp b/contrib/sb-posix/macros.lisp
index f80e714..e9ec78b 100644
--- a/contrib/sb-posix/macros.lisp
+++ b/contrib/sb-posix/macros.lisp
@@ -1,20 +1,63 @@
 (in-package :sb-posix)
 
-(define-designator filename c-string
+(define-designator filename (string c-string)
+  ("A STRING designating a filename in native namestring syntax.
+
+Note that native namestring syntax is distinct from Lisp namestring syntax:
+
+  \(pathname \"/foo*/bar\")
+
+is a wild pathname with a pattern-matching directory component.
+SB-EXT:PARSE-NATIVE-NAMESTRING may be used to construct Lisp pathnames that
+denote POSIX filenames as understood by system calls, and
+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 MY-DEFAULTS for which
+
+  \(merge-pathnames (make-pathname :name \"FOO\" :case :common)
+                    my-defaults)
+
+returns a pathname that denotes a file in the directory, supply a true
+:AS-DIRECTORY argument to SB-EXT:PARSE-NATIVE-NAMESTRING. Likewise, to supply
+the name of a directory to a POSIX function in non-directory syntax, supply a
+true :AS-FILE argument to SB-EXT:NATIVE-NAMESTRING."
+   "Designator for a FILENAME: a STRING designating itself, or a
+designator for a PATHNAME designating the corresponding native namestring."
+   "Converts FILENAME-DESIGNATOR into a FILENAME.")
   (pathname
    (sb-ext:native-namestring (translate-logical-pathname filename)
                              :as-file t))
-  (string filename))
+  (string
+   filename)
+  (stream
+   (filename (pathname filename))))
+
+(define-designator file-descriptor (fixnum (integer 32))
+    ("A FIXNUM designating a native file descriptor.
+
+SB-SYS:MAKE-FD-STREAM can be used to construct a FILE-STREAM associated with a
+native file descriptor.
 
-(define-designator file-descriptor (integer 32)
-  (file-stream (sb-sys:fd-stream-fd file-descriptor))
-  (fixnum file-descriptor))
+Note that mixing I/O operations on a FILE-STREAM with operations directly on its
+descriptor may produce unexpected results if the stream is buffered."
+     "Designator for a FILE-DESCRIPTOR: either a fixnum designating itself, or
+a FILE-STREAM designating the underlying file-descriptor."
+     "Converts FILE-DESCRIPTOR-DESIGNATOR into a FILE-DESCRIPTOR.")
+  (file-stream
+   (sb-sys:fd-stream-fd file-descriptor))
+  (fixnum
+   file-descriptor))
 
-(define-designator sap-or-nil sb-sys:system-area-pointer
+(define-designator sap-or-nil (sb-sys:system-area-pointer sb-sys:system-area-pointer)
+    ()
   (null (sb-sys:int-sap 0))
   (sb-sys:system-area-pointer sap-or-nil))
 
-(define-designator alien-pointer-to-anything-or-nil (* t)
+(define-designator alien-pointer-to-anything-or-nil (sb-alien-internals::alien-value (* t))
+    ()
   (null (sb-alien:sap-alien (sb-sys:int-sap 0) (* t)))
   ((alien (* t)) alien-pointer-to-anything-or-nil))