Osicat Manual

draft version 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.

Table of Contents

1 Osicat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1 Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.4 Files and Symbolic Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.5 Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.6 Time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.7 Pathname Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

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 nonwild 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. setffile-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 withtemporary-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 6

Index

A

absolute-pathname. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 absolute-pathname-p . . . . . . . . . . . . . . . . . . . . . . . . . . 4

C

current-directory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

D

delete-directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

delete-directory-and-files . . . . . . . . . . . . . . . . . . 2

directory-exists-p . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 directory-pathname-p . . . . . . . . . . . . . . . . . . . . . . . . . 5

E

environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 environment-variable . . . . . . . . . . . . . . . . . . . . . . . . . 1

F

file-exists-p . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 file-kind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 file-permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

G

get-monotonic-time . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

L

list-directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

M

make-link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

makunbound-environment-variable. . . . . . . . . . . . . 1

mapdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

O

open-temporary-file . . . . . . . . . . . . . . . . . . . . . . . . . . 4

P

pathname-as-directory . . . . . . . . . . . . . . . . . . . . . . . . 5 pathname-as-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

pathname-directory-pathname . . . . . . . . . . . . . . . . . 5

R

read-link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 regular-file-exists-p . . . . . . . . . . . . . . . . . . . . . . . . 3 relative-pathname-p . . . . . . . . . . . . . . . . . . . . . . . . . . 5

S

system-error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

U

unmerge-pathnames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 user-info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

W

walk-directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

with-directory-iterator . . . . . . . . . . . . . . . . . . . . . . 3

with-temporary-file . . . . . . . . . . . . . . . . . . . . . . . . . . 4