-(in-package :sb-posix-internal)
-
-;;; some explanation may be necessary. The namestring "[foo]"
-;;; denotes a wild pathname. When there's a file on the disk whose
-;;; Unix name is "[foo]", the appropriate CL namestring for it is
-;;; "\\[foo]". So, don't call NAMESTRING, instead call a function
-;;; that gets us the Unix name
-(defun native-filename (pathname)
- (let ((directory (pathname-directory pathname))
- (name (pathname-name pathname))
- (type (pathname-type pathname)))
- (with-output-to-string (s nil :element-type 'base-char)
- (etypecase directory
- (string (write-string directory s))
- (list
- (when (eq (car directory) :absolute)
- (write-char #\/ s))
- (dolist (piece (cdr directory))
- (etypecase piece
- (string (write-string piece s) (write-char #\/ s))))))
- (etypecase name
- (null)
- (string (write-string name s)))
- (etypecase type
- (null)
- (string (write-char #\. s) (write-string type s))))))
-
-(define-designator filename c-string
- (pathname
- (native-filename (translate-logical-pathname filename)))
- (string filename))
-
-(define-designator file-descriptor (integer 32)
- (sb-impl::file-stream (sb-impl::fd-stream-fd file-descriptor))
- (fixnum file-descriptor))
-
-(define-designator sap-or-nil sb-sys:system-area-pointer
+(in-package :sb-posix)
+
+(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)
+ (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.
+
+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 sb-sys:system-area-pointer)
+ ()