Table of Contents ***************** osicat 1 Osicat 1.1 Conditions 1.2 Environment 1.3 Directories 1.4 Files and Symbolic Links 1.5 Users 1.6 Time 1.7 Pathname Utilities Index osicat ****** Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 1 Osicat ******** -- Package: osicat Osicat is a lightweight operating system interface for Common Lisp on Unix-platforms. It is not a POSIX-style `api', but rather a simple lispy accompaniment to the standard `ansi' facilities. Osicat homepage: http://www.common-lisp.net/project/osicat/ Concepts: Designated directory When a relative pathname designator is used as a directory designator it is first resolved against `*default-pathname-default*', and then against the current directory. (With `merge-pathnames' in both cases.) 1.1 Conditions ============== -- Condition: system-error Class precedence list: `system-error, error, serious-condition, condition, t' Base class for errors signalled by Osicat. 1.2 Environment =============== -- Function: environment-variable name `environment-variable' returns the environment variable identified by `name', or `nil' if one does not exist. `name' can either be a symbol or a string. `setf' `environment-variable' sets the environment variable identified by `name' to `value'. Both `name' and `value' can be either a symbols or strings. Signals an error on failure. -- Function: environment `environment' returns the current environment as an assoc-list. `setf' `environment' modifies the environment its argument. Often it is preferable to use `setf' `environment-variable' and `makunbound-environment-variable' to modify the environment instead of `setf' `environment'. -- Function: makunbound-environment-variable name Removes the environment variable identified by `name' from the current environment. `name' can be either a string or a symbol. Returns the string designated by `name'. Signals an error on failure. 1.3 Directories =============== -- Function: current-directory `current-directory' returns the operating system's current directory, which may or may not correspond to `*default-pathname-defaults*'. `setf' `current-directory' changes the operating system's current directory to the `pathspec'. An error is signalled if the `pathspec' is wild or does not designate a directory. -- Function: delete-directory-and-files dirname &key if-does-not-exist Recursively deletes all files and directories within the directory designated by the non-wild pathname designator `dirname' including `dirname' itself. `if-does-not-exist' must be one of `:error' or `:ignore' where `:error' means that an error will be signaled if the directory `dirname' does not exist. -- Function: delete-directory pathspec Deletes the directory designated by `pathspec'. Returns `t'. The directory must be empty. Symbolic links are not followed. Signals an error if `pathspec' is wild, doesn't designate a directory, or if the directory could not be deleted. -- Function: directory-exists-p pathspec Checks whether the file named by the pathname designator `pathspec' exists and is a directory. Returns its truename if this is the case, `nil' otherwise. Follows symbolic links. -- Function: list-directory pathspec &key bare-pathnames Returns a fresh list of pathnames corresponding to all files within the directory named by the non-wild pathname designator `pathspec'. If `bare-pathnames' is non-NIL only the files's bare pathnames are returned (with an empty directory component), otherwise the files' pathnames are merged with `pathspec'. -- Function: mapdir function pathspec Applies function to each entry in directory designated by `pathspec' in turn and returns a list of the results. Binds `*default-pathname-defaults*' to the directory designated by pathspec round to function call. If `pathspec' designates a symbolic link, it is implicitly resolved. Signals an error if `pathspec' is wild or doesn't designate a directory. -- Function: walk-directory dirname fn &key directories if-does-not-exist test Recursively applies the function `fn' to all files within the directory named by the non-wild pathname designator `dirname' and all of its sub-directories. Returns `t' on success. `fn' will only be applied to files for which the function `test' returns a true value. If `directories' is not `nil', `fn' and `test' are applied to directories as well. If `directories' is `:depth-first', `fn' will be applied to the directory's contents first. If `directories' is `:breadth-first' and `test' returns `nil', the directory's content will be skipped. `if-does-not-exist' must be one of `:error' or `:ignore' where `:error' means that an error will be signaled if the directory `dirname' does not exist. -- Macro: with-directory-iterator (iterator pathspec) &body body `pathspec' must be a valid directory designator: `*default-pathname-defaults*' is bound, and (CURRENT-DIRECTORY) is set to the designated directory for the dynamic scope of the body. Within the lexical scope of the body, `iterator' is defined via macrolet such that successive invocations of (ITERATOR) return the directory entries, one by one. Both files and directories are returned, except '.' and '..'. The order of entries is not guaranteed. The entries are returned as relative pathnames against the designated directory. Entries that are symbolic links are not resolved, but links that point to directories are interpreted as directory designators. Once all entries have been returned, further invocations of (ITERATOR) will all return `nil'. The value returned is the value of the last form evaluated in body. Signals an error if `pathspec' is wild or does not designate a directory. 1.4 Files and Symbolic Links ============================ -- Function: file-exists-p pathspec &optional file-kind Checks whether the file named by the pathname designator `pathspec' exists, if this is the case and `file-kind' is specified it also checks the file kind. If the tests succeed, return two values: truename and file kind of `pathspec', `nil' otherwise. Follows symbolic links. -- Function: regular-file-exists-p pathspec Checks whether the file named by the pathname designator `pathspec' exists and is a regular file. Returns its truename if this is the case, `nil' otherwise. Follows symbolic links. -- Function: file-kind pathspec &key follow-symlinks Returns a keyword indicating the kind of file designated by `pathspec', or `nil' if the file does not exist. Does not follow symbolic links by default. Possible file-kinds in addition to `nil' are: `:regular-file', `:symbolic-link', `:directory', `:pipe', `:socket', `:character-device', and `:block-device'. If `follow-symlinks' is non-NIL and `pathspec' designates a broken symlink returns `:broken' as second value. Signals an error if `pathspec' is wild. -- Function: file-permissions pathspec `file-permissions' returns a list of keywords identifying the permissions of `pathspec'. `setf' `file-permissions' sets the permissions of `pathspec' as identified by the symbols in list. If `pathspec' designates a symbolic link, that link is implicitly resolved. Permission symbols consist of `:user-read', `:user-write', `:user-exec', `:group-read', `:group-write', `:group-exec', `:other-read', `:other-write', `:other-exec', `:set-user-id', `:set-group-id', and `:sticky'. Both signal an error if `pathspec' is wild, or doesn't designate an existing file. -- Function: open-temporary-file &key pathspec element-type external-format Creates a temporary file setup for input and output, and returns a stream connected to that file. `pathspec' serves as template for the file to be created: a certain number of random characters will be concatenated to the file component of `pathspec'. If `pathspec' has no directory component, the file will be created inside `*temporary-directory*'. The file itself is unlinked once it has been opened. `element-type' specifies the unit of transaction of the stream. Consider using `with-temporary-file' instead of this function. On failure, a `file-error' may be signalled. -- Macro: with-temporary-file (stream &key pathspec element-type external-format) &body body Within the lexical scope of the body, `stream' is connected to a temporary file as created by `open-temporary-file'. The file is closed automatically once `body' exits. -- Function: make-link link &key target hard Creates `link' that points to `target'. Defaults to a symbolic link, but giving a non-NIL value to the keyword argument `:hard' creates a hard link. Returns the pathname of the link. Relative targets are resolved against the link. Relative links are resolved against `*default-pathname-defaults*'. Signals an error if either target or link is wild, target does not exist, or link exists already. -- Function: read-link pathspec Returns the pathname pointed to by the symbolic link designated by `pathspec'. If the link is relative, then the returned pathname is relative to the link, not `*default-pathname-defaults*'. Signals an error if `pathspec' is wild, or does not designate a symbolic link. 1.5 Users ========= -- Function: user-info id `user-info' returns the password entry for the given name or numerical user `id', as an assoc-list. 1.6 Time ======== -- Function: get-monotonic-time Gets current time in seconds from a system's monotonic clock. 1.7 Pathname Utilities ====================== -- Function: absolute-pathname-p pathspec Returns `t' if the `pathspec' designates an absolute pathname, `nil' otherwise. -- Function: absolute-pathname pathspec &optional default Returns an absolute pathname corresponding to `pathspec' by merging it with `default', and (CURRENT-DIRECTORY) if necessary. -- Function: directory-pathname-p pathspec Returns `nil' if `pathspec' (a pathname designator) does not designate a directory, `pathspec' otherwise. It is irrelevant whether file or directory designated by `pathspec' does actually exist. -- Function: pathname-as-directory pathspec Converts the non-wild pathname designator `pathspec' to directory form. -- Function: pathname-as-file pathspec Converts the non-wild pathname designator `pathspec' to file form. -- Function: pathname-directory-pathname pathspec Returns the directory part of `pathspec' as a pathname. -- Function: relative-pathname-p pathspec Returns `t' if the `pathspec' designates a relative pathname, `nil' otherwise. -- Function: unmerge-pathnames pathspec &optional default Removes those leading directory components from `pathspec' that are shared with `default'. Index ***** absolute-pathname: See 1.7. (line 289) absolute-pathname-p: See 1.7. (line 285) current-directory: See 1.3. (line 99) delete-directory: See 1.3. (line 115) delete-directory-and-files: See 1.3. (line 108) directory-exists-p: See 1.3. (line 122) directory-pathname-p: See 1.7. (line 293) environment: See 1.2. (line 82) environment-variable: See 1.2. (line 73) file-exists-p: See 1.4. (line 184) file-kind: See 1.4. (line 196) file-permissions: See 1.4. (line 209) get-monotonic-time: See 1.6. (line 279) list-directory: See 1.3. (line 127) make-link: See 1.4. (line 250) makunbound-environment-variable: See 1.2. (line 90) mapdir: See 1.3. (line 134) open-temporary-file: See 1.4. (line 228) pathname-as-directory: See 1.7. (line 299) pathname-as-file: See 1.7. (line 303) pathname-directory-pathname: See 1.7. (line 306) read-link: See 1.4. (line 261) regular-file-exists-p: See 1.4. (line 191) relative-pathname-p: See 1.7. (line 309) system-error: See 1.1. (line 64) unmerge-pathnames: See 1.7. (line 313) user-info: See 1.5. (line 272) walk-directory: See 1.3. (line 147) with-directory-iterator: See 1.3. (line 162) with-temporary-file: See 1.4. (line 245)