Index: /trunk/source/doc/src/using.xml
===================================================================
--- /trunk/source/doc/src/using.xml (revision 14793)
+++ /trunk/source/doc/src/using.xml (revision 14794)
@@ -1624,6 +1624,122 @@
to the directory containing the current heap image.
-
-
+
+ Pathname Namestrings
+
+ The syntax of namestrings is implementation-defined in Common Lisp.
+ Portable programs cannot assume much of anything about them. (See
+ section 19.1.1 of the Common Lisp standard for more information.)
+
+
+ When translating a namestring into a pathname object, most
+ implementations seem to follow the convention that a dot
+ character in the namestring separates the
+ pathname-name and
+ the pathname-type. When there is more
+ than one dot in involved, or when dots appear at the beginning
+ or end of the namestrings, what to do is less clear: does
+ ".emacs" describe a pathname whose name is
+ nil and whose type is emacs
+ or something else? Similarly, given "a.b.c", the question
+ is which parts are parsed as the pathname name, and which are
+ parsed as the pathname type?
+
+
+ When generating a namestring from a pathname object (as happens,
+ for example, when printing a pathname), &CCL;
+ tries to avoid some potential ambiguity by escaping characters
+ that might otherwise be used to separate pathname components.
+ The character used to quote or escape the separators is a
+ backlash on Unix systems, and a #\> character on Windows.
+ So, for example, "a\\.b.c"
+ has name "a.b" and type "c", whereas "a.b\\.c" has name
+ "a" and type "b.c".
+
+
+ To get a native namestring suitable for passing to an
+ operating system command, use the function
+ ccl:native-translated-namestring.
+
+
+
+ Working with native namestrings
+
+
+ native-translated-namestring
+
+
+
+ native-translated-namestring
+
+ Return a namestring that uses the conventions of the
+ native operating system.
+
+ Function
+
+
+
+ native-translated-namestring pathname-designator
+
+
+ Description
+
+ This function returns a namestring that represents a pathname
+ using the native conventions of the operating system.
+ Any quoting or escaping of special characters will be removed.
+
+
+ For example, suppose that p is a pathname made
+ by (make-pathname :name "a.b" :type "c").
+ Then, (native-translated-namestring p) evaluates
+ to "a.b.c". By contrast, (namestring p) evaluates
+ to "a\\.b.c".
+
+
+
+
+
+
+ with-filename-cstrs
+
+
+
+ with-filename-cstrs
+
+ Suitably encode strings to be used as filenames for foreign code.
+
+ Macro
+
+
+
+ with-filename-cstrs ( {(var value)}* ) {form}*
+
+
+ Description
+
+ Executes forms in an environemt in which each
+ var is bound to a stack-allocated foreign
+ pointer which refers to a C-style string suitable for passing
+ to foreign code which expects a filename argument.
+
+
+ For example, one might use this macro in the following way:
+
+(with-filename-cstrs ((s (native-translated-namestring pathname)))
+ (#_unlink s))
+
+
+
+ Various operating systems have different conventions for how
+ they expect native pathname strings to be encoded. Darwin
+ expects then to be decomposed UTF-8. The Unicode variants
+ to Windows file-handling functions expect UTF-16. Other
+ systems just treat them as opaque byte sequences. This macro
+ ensures that the correct encoding is used, whatever
+ the host operating system.
+
+
+
+
+
OS X (Darwin)