REF FILESYS                               Titch Le Bek, Rob Duncan, 1986

       COPYRIGHT University of Sussex 1993. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<       LISP FILE SYSTEM      >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<          PROCEDURES         >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

This file  briefly  describes  the functions,  variables  and  constants
documented in Chapter 23  of the standard Common  Lisp guide, which  is:
Common Lisp: The Language (Guy L. Steele, Digital Press, 1984).


-------------------------------------------------
1  A Listing of Functions Variables and Constants
-------------------------------------------------

*default-pathname-defaults*                                   [variable]
        The value of this variable should  be a pathname. It is used  to
        provide default pathname  components for  any pathname  function
        that   needs   them   (i.e.   make-pathname,   parse-namestring,
        merge-pathnames, & enough-namestring).


(delete-file file)                                            [function]
        file  is  deleted.  Returns  a  non-nil  value  if   successful.
        Otherwise an error is signaled.


(directory pathname &key)                                     [function]
        Returns a  list of  pathnames, one  for each  file in  the  file
        system that matches pathname.


(directory-namestring pathname)                               [function]
        Returns the directory portion of pathname.


(enough-namestring pathname &optional defaults)               [function]
        Returns an  abbreviated namestring  sufficient to  identify  the
        pathname file.


(file-author file)                                            [function]
        Returns the author of file or nil if this cannot be determined.


(file-length file-stream)                                     [function]
        Returns the length of file as  a non-negative integer or nil  if
        this cannot be determined.


(file-namestring pathname)                                    [function]
        Returns  a  string  representing  the  name,  type  and  version
        components of pathname.


(file-position stream position)                               [function]
        Returns or sets the current position within a random-access file
        stream to be position.


(file-string-length file-stream object)                       [function]
        object must be a string  or a character. Returns the  difference
        (as an integer)  between what the  file-position of  file-stream
        would be before and after writing object to the file-stream.


(file-write-date file)                                        [function]
        Returns the time  at which  the file  file was  created or  last
        written, as an integer in  universal-time-format or nil if  this
        cannot be determined.


(host-namestring pathname)                                    [function]
        Returns the host name portion of pathname.


(load filename &key :verbose :print :if-does-not-exist)       [function]
        Loads the file named by  filename into the Lisp environment.  If
        filename is a  stream rather  than a pathname,  then load  loads
        directly from the  stream. :verbose,  if true,  permits load  to
        print a  message in  the form  of a  comment. :print,  if  true,
        causes the  value of  each expression  loaded to  be printed  to
        *standard-output*. If  :if-does-not-exist  is specified  and  is
        nil, load returns nil rather than signaling an error if the file
        does not exist.


(load-logical-pathname-translations host)                     [function]
        If a  logical pathname  host named  host (a  string) is  already
        defined, this function returns nil. Otherwise, it searches for a
        logical pathname  host definition  in an  implementation-defined
        manner. If none is found, it  signals an error. If a  definition
        is found, it installs the definition and returns t.


*load-pathname*                                               [variable]
        Bound by load to the  pathname given as argument (after  merging
        with *default-pathname-defaults*).


*load-print*                                                  [variable]
        Used as the  default for  the :print  argument to  load. So,  if
        true, (its  initial value  is nil),  load prints  the values  of
        top-level forms to *standard-output*.


*load-truename*                                               [variable]
        Bound by load to the truename of the file being loaded.


*load-verbose*                                                [variable]
        *load-verbose*  provides  the  default  value  of  the  :verbose
        argument to load. Initial value: t.


(logical-pathname object)                                     [function]
        Converts object to a logical pathname (if possible) and  returns
        it. object  may  be  a  logical  pathname,  a  logical  pathname
        namestring containing a  host component, or  a stream for  which
        the pathname function returns a logical pathname. For any  other
        argument, logical-pathname signals an error of type type-error.


(logical-pathname-translations host)                          [function]
        If the specified  host is not  the host component  of a  logical
        pathname and is not a string that has been defined as a  logical
        pathname host  name  by setf  of  logical-pathname-translations,
        this function signals an error of type type-error; otherwise, it
        returns the list of translations for the specified host.


(make-load-form object)                               [generic-function]
        Methods on make-load-form should return two values: a  `creation
        form', which  when  evaluated  at load-time  returns  an  object
        equivalent to the argument object, and an `initialisation form',
        which when evaluated initialises the slots or components of  the
        object created by the creation form.


(make-load-form-saving-slots object &optional slot-names)     [function]
        This returns two values (a  creation form and an  initialisation
        form) suitable for return  from a make-load-form method.  object
        must be  of  metaclass standard-class  or  structure-class.  The
        optional argument slot-names should  be a list  of the names  of
        slots whose  values  are  to  be  preserved.  If  slot-names  is
        unsupplied, the returned initialisation  form will contain  code
        initialise all local slots in object.


(make-pathname &key :host :device :directory                  [function]
                    :name :type :version :defaults)
        Constructs  and  returns  a   pathname.  After  the   components
        specified explicitly by the keywords are filled in, the  merging
        rules used by merge-pathnames  are used to  fill in any  missing
        components  from  the  defaults   specified  by  the   :defaults
        argument. :defaults defaults to a pathname whose host  component
        is  the   same  as   the  host   component  of   the  value   of
        *default-pathname-defaults* and whose other components are nil.


(merge-pathnames pathname                                     [function]
                &optional defaults default-version)
        merge-pathnames is called to process a file name supplied by the
        user. Unspecified  components of  pathname  are filled  in  from
        defaults and returns  a new pathname.  defaults defaults to  the
        value of  *default-pathname-defaults*. default-version  defaults
        to :newest.


(namestring pathname)                                         [function]
        Returns the full form of pathname as a string.


(open filename &key :direction :element-type                  [function]
                    :if-exists :if-does-not-exist)
        Returns a stream connected to filename. The keyword args specify
        what kind of stream to produce and how to handle errors.


(parse-namestring string                                      [function]
                    &optional host defaults
                    &key :start :end :junk-allowed)

        This turns string into a pathname. If host is non-nil it must be
        a host  name  that  could  appear in  the  host  component  of a
        pathname, or nil. If host is nil then the host name is extracted
        from   defaults    (which    defaults   to    the    value    of
        *default-pathname-defaults*).  parse-namestring  parses  a  file
        name in pathname within the range delimited by :start and  :end.
        If :junk-allowed is not  nil, then the  first value returned  is
        the pathname parsed, or nil if no syntactically correct pathname
        was seen. If :junk-allowed is  nil then the entire substring  is
        scanned and the parsed pathname  returned. An error is  signaled
        if the substring does not consist entirely of the representation
        of a pathname. The second value is the index into the string  of
        the delimiter that terminated the parse, or the index beyond the
        substring if the parse terminated at the end of the substring.


(pathname object)                                            [function]
        Converts object to be a pathname which is returned.


(pathname-device pathname)                                    [function]
        Returns the  device  component  of  pathname.


(pathname-directory pathname)                                 [function]
        Returns the  directory component  of pathname.


(pathname-host pathname)                                      [function]
        Returns  the  host  component  of  pathname.


(pathname-match-p pathname wildname)                          [function]
        Returns t if pathname matches wildname; nil otherwise.


(pathname-name pathname)                                      [function]
        Returns  the  name  component  of  pathname.


(pathname-type pathname)                                      [function]
        Returns the type component of pathname as a string or symbol.


(pathname-version pathname)                                   [function]
        Returns the vesion component of pathname as a number or symbol.


(pathnamep object)                                            [function]
        Returns t if object is a pathname; nil otherwise.


(probe-file file)                                             [function]
        Returns nil if there is no file named file and otherwise returns
        a pathname that is the true name of the file. If file is an open
        stream associated with a file then probe-file cannot return  nil
        but will produce the true name of the associated file.


(rename-file file name)                                       [function]
        Renames  file  with  name.  If  successful,  three  values   are
        returned: the first is name  with any missing components  filled
        in by performing a merge-pathnames  operation using file as  the
        defaults; the  second is  the  truename of  file before  it  was
        renamed and the third is the  truename of the file after it  was
        renamed.


(translate-logical-pathname pathname &key)                    [function]
        Translates a  logical  pathname to  the  corresponding  physical
        pathname. The pathname argument is first coerced to a  pathname.
        If it is  not a pathname,  string, or file  stream, an error  of
        type type-error  is  signaled.  If  the  coerced  argument  is a
        physical pathname, it is returned.


(translate-pathname source from-wildname                      [function]
                           to-wildname &key)

        Translates the pathname source, which must match  from-wildname,
        into  a  corresponding  pathname  (call  it  result),  which  is
        constructed so as to match to-wildname, and returns result.

        This operation is performed by examining corresponding pieces of
        the three  pathnames  in  turn,  where a  piece  is  a  pathname
        component or a list element of a structured component such  as a
        hierarchical  directory.  Hierarchical  directory  elements   in
        from-wildname and to-wildname  are matched by  whether they  are
        wildcards, not by depth in the directory hierarchy. If the piece
        in to-wildname is present  and not wild, it  is copied into  the
        result. If  the  piece  in  to-wildname is  :wild  or  nil,  the
        corresponding  piece  in  source  is  copied  into  the  result.
        Otherwise, the piece in to-wildname might be a complex  wildcard
        such as  "foo*bar"; the  portion  of the  piece in  source  that
        matches the  wildcard  portion  of the  corresponding  piece  in
        from-wildname (or the entire source piece, if the  from-wildname
        piece is  not  wild  and  therefore  equals  the  source  piece)
        replaces the wildcard  portion of the  piece in to-wildname  and
        the value produced is used in the result.


(truename pathname)                                           [function]
        Returns the true name of the file associated with pathname.


(user-homedir-pathname &optional host)                        [function]
        Returns the pathname  for the user's  "home directory" on  host.
        This function never returns nil  if host is not specified  but a
        pathname without any name, type or version component.


(wild-pathname-p pathname)                                    [function]
        Returns t  if pathname  is  "wild", i.e.  at  least one  of  the
        components is  the keyword  :wild, or  a string  containing  the
        wild-card character "*". Returns nil if pathname is not wild.


(with-open-file (var filename {options}*)                        [macro]
                {declaration}*
                {form}*)
        The {form}* is evaluated with var  bound to a stream that  reads
        or writes the file named by filename. {options}* is evaluated to
        produce keyword arguments to open. The file is always closed  on
        exit.



--- C.all/lisp/ref/filesys
--- Copyright University of Sussex 1995. All rights reserved.
