Operating System Interface

This document contains the following sections:

1.0 Operating-system interface

This chapter describes some functions in Allegro CL that interact with the host operating system. These functions include those providing access and control of system services, which, on UNIX and Linux, are typically found in chapters 2 and 3 of the UNIX manual.

A :osi module is described in Section 7.0 The Operating System Interface (OSI) module below. Functionality described in all sections of this document is enhanced, so every section is changed in some fashion. The operators, constants, and classes of the new module are not described (in this documentation release) on individual documentation pages. Instead, the descriptions are in Appendix A Operating System Interface Functionality.

2.0 Subprocess functions

The new OSI interface (see Section 7.0 The Operating System Interface (OSI) module) includes the function command-output and the macros with-command-output and with-command-io. Those operators also execute operating system commands and can be used along with or in place of the functions described in this section. They are higher-level than run-shell-command and shell and are now recommended when the interaction with the subprocess requires input or produces output that must be captured. The new operators do not have separate description pages. They are described in Appendix A.9 OSI process/uid/gid interface functions.

Allegro CL has the ability to run UNIX and Windows child processes controlled from Lisp. Starting a subprocess and communicating with it are slower than using the foreign function interface to accomplish the same task, but it is sometimes unavoidable. Creating very many simultaneous subprocesses may be limited by system resources.

Subprocesses can be started with run-shell-command and shell, and with the newly-added operators command-output, with-command-output, and with-command-io.

If run-shell-command is called with the wait keyword argument nil, reap-os-subprocess (or os-wait) must be called to clear the process from the system. Failure to do this will eventually cause the system to be unable to create new processes. Further, the streams opened by run-shell-command must be closed by the program. The system will not close them automatically. In contrast, the newly-added operators command-output, with-command-output, and with-command-io handle reaping the processes and closing the stream themselves.

Here are a couple of examples, both on Unix, of run-shell-command followed by examples using the new functionality. (There are more examples of using run-shell-command on its description page).

In the first, we simply have run-shell-command execute a simple command (who).

USER(1): (run-shell-command "who")
sdj       ttyp0       Aug 18 16:08 (rubix)
adam      ttyp2       Aug 18 16:17 (rubix)
dm        ttyp4       Aug 19 10:24 (rubix)
0
USER(2):

The second example is more complicated. We cause run-shell-command to spawn a shell and then we communicate with the shell via the stream set up by run-shell-command.

;; First we define a function to read the output from the shell. This
;; function is pretty simple -- it reads characters and prints them
;; out but it does show how a more useful function could be implemented.
USER(24): (defun get-from-shell (stream)
             (do ((ch (read-char-no-hang stream)
                      (read-char-no-hang stream)))
                 ((null ch))
              (write-char ch)))
GET-FROM-SHELL
;; Now we initiate the shell:
USER(25): (setq shell-stream (excl:run-shell-command "csh"
                                :input :stream
                                :output :stream
                                :wait nil))
#<EXCL::BIDIRECTIONAL-TERMINAL-STREAM @ #x10a4aa6>
USER(26): (format shell-stream "who~%")
NIL
USER(27): (force-output shell-stream)
NIL
USER(28): (get-from-shell shell-stream)
rlogin ttya Aug 19 07:06
rlogin ttyb Aug 19 08:26
sdj ttyp0 Aug 18 16:08 (rubix)
cheetham ttyp1 Aug 18 17:17 (frozen)
adam ttyp2 Aug 18 16:17 (rubix)
NIL
;; We exit the shell:
USER(29): (format shell-stream "exit~%")
NIL
;; and close the stream.
USER(30): (close shell-stream)
T
;; We call sys:reap-os-subprocess because we called 
;; run-shell-command with :wait nil:
USER(31): (sys:reap-os-subprocess)
0
27201
USER(32):

Here are some examples using the new operators command-output, with-command-output, and with-command-io.

cl-user(1): (require :osi)
;; fast-loading osi.fasl
t
cl-user(2): (use-package :excl.osi)
t
cl-user(3): (command-output "who")
("mikel    pts/0    Oct  3 15:38 (ultra)"
 "layer    pts/1    Oct 22 10:26 (crikey)")
nil
0
cl-user(4): (command-output "who" :whole t)
"mikel    pts/0    Oct  3 15:38 (ultra)
layer    pts/1    Oct 22 10:26 (crikey)
"
nil
0
cl-user(5): (command-output "cat" :input "this is multi-line
input for the cat program")
("this is multi-line" "input for the cat program")
nil
0
cl-user(6): (with-command-io ("cat")
	      (:input (stream)
		(format stream "cat this~%")
		(format stream "cat this, too~%"))
	      (:output (line)
		(format t "output: ~a~%" line)))
output: cat this
output: cat this, too
0
cl-user(7): (with-command-output (line "cat /etc/issue")
	      (format t "output: ~a~%" line))
output: 
output: Red Hat Linux release 6.0 (Hedwig)
output: Kernel 2.2.19 on an i686
output: 
0
cl-user(8): 

3.0 Filesystem manipulation functions

The new OSI interface (see Section 7.0 The Operating System Interface (OSI) module) includes many operators related to the file system, similar to the operators described in this section. See Appendix A.1 OSI file handling functionality for descriptions of all the new functionality relevant to this section.

The following functions provide information about directories in the system:

Examples using excl:chdir. The current users home directory is /usr/tech/doe/. The directory /usr/tech/doe/tmp/ exists. The Allegro directory for the Lisp is (in this example) /usr/acl70/.

user(15): (chdir) ;; no argument: change to user home directory
"/usr/tech/doe/"
user(16): (chdir "sys:") ;; a string naming a logical pathname 
                                   ;; which translates
                                   ;; to the Lisp home directory.
"/usr/acl70/"
user(17): (chdir)
"/usr/tech/doe/"
user(18): (chdir "tmp") ;; change to the tmp/ subdirectory
"tmp/"
user(19): (chdir (make-pathname :directory "tmp")) 
                                  ;; The absolute directory 
                                  ;; /tmp/
"/tmp/"
user(20): (chdir)
"/usr/tech/doe/"
user(21): 

The following functions provide information about or manipulate files and/or directories:

The :osi module has many new functions associated with filesystem manipulation. See Appendix A.1 OSI file handling functionality for descriptions of the new functionality.

4.0 Temporary directory and files

The OSI interface (see Section 7.0 The Operating System Interface (OSI) module) includes operators like mkstemp, mkdtemp, and with-open-temp-file. These operators provide functionality related to the operators described in this section. See Appendix A.1 OSI file handling functionality.

Allegro CL may need to write temporary files while it runs. The first function following returns the directory used by the current running Lisp as its temporary directory. The second returns an unused filename in that directory.

5.0 Accessing command-line arguments

Allegro CL may be called with any number of arguments on the command line. Some of these arguments are used by Allegro CL itself (to suppress reading of initialization files, for example) and others are simply collected and made available to the running Lisp.

Lisp uses `--' as a delimiter between arguments used by Allegro CL when starting up and arguments simply collected and made available after Lisp has started. All arguments before the first appearance of `--' are used by Allegro CL and any improper arguments before that marker will cause Allegro CL to signal a warning. All arguments after the first appearance of `--' are ignored by Allegro CL when starting up and are available after startup, accessible with the following functions. Note that the arguments before the `--' are also available with these functions. Note too that Lisp can be created so it ignores all command-line arguments (simply making all available after startup). This will happen if an image is created with dumplisp with ignore-command-line-arguments specified as true.

Further, if no -I argument is provided (to specify an image file, so the image file with the same name and in the same directory as the executable is used), the command line will look like a -I argument was specified, as shown in the examples.

See with-command-line-arguments, which is a macro that can be used to process command-line arguments. See Command line arguments in startup.htm for information on command-line-arguments. The functions that access command-line arguments are shown in the following table. + arguments, which are Windows specific and affect how the executable starts up on Windows, are discarded and not included in the information returned returned by any of the command-line argument functions.

The application keyword argument, if t (the default) leaves out any arguments before the first `--' and leaves out the `--' (so if `--' doesn't appear, the list containing only the executable name is returned). If nil, all arguments are considered.

The purpose of these functions is to allow you to customize the running of Lisp when the image is invoked. As a simple example, suppose you invoke Lisp as follows:

mlisp -qq -- foo -batch bar 

Here, mlisp is the name of the Allegro CL executable. Note first that Lisp will not run in batch mode since the -batch appears after `--'. However, no initialization file will be read since the -qq argument appears before the `--'. See startup.htm for more information on command line arguments which affect how Lisp starts up. As we said above, the command line arguments will show -I <image.dxl> arguments even though they were not specified.

Here is what the various command line functions return given that command line:

(sys:command-line-argument 0) [returns] "mlisp"
(sys:command-line-argument 1) [returns] "foo"
(sys:command-line-argument 1 :application nil) [returns] "-I"
(sys:command-line-arguments) [returns] ("mlisp" "foo"
"-batch" "bar")
(sys:command-line-arguments :application nil) 
   [returns] ("mlisp" "-I" "mlisp.dxl"
"-qq" "--" "foo" "-batch" "bar")
(sys:command-line-argument-count) [returns] 4
(sys:command-line-argument-count :application nil) [returns] 8

You may use this information as you see fit. One possible use, for example, is to have some function defined and run (perhaps in an initialization file) which takes some action (such as loading specific files) based on the values of the arguments.

6.0 Polling and setting environment variables

The OSI interface (see Section 7.0 The Operating System Interface (OSI) module) includes more operators for setting, changing, and unsetting environment variables. These are described Appendix A.11 OSI miscellaneous low-level functionality.

The function sys:getenv returns (and with setf sets) the value of an environment variable. The functions setenv, putenv, and unsetenv set and unset environment variables. The function environment returns a list of environment variables and values in the original environment when Lisp was started (with later changes not reflected). These functions are in the OSI interface module mentioned above. Note that setenv and unsetenv are not supported on all operating systems (see the descriptions for details). sys:getenv and putenv are supported on all systems.

;; Here is an example using getenv and the new functions
;; setenv and unsetenv. It may be that the environment variables
;; exist on your system, in which case you will see different 
;; values and may not wish to unset them. SETENV and UNSETENV 
;; are not supported on all platforms.
cl-user(3): (getenv "FOO")
nil
cl-user(4): (setf (getenv "FOO") "bar")
"bar"
cl-user(5): (getenv "FOO")
"bar"
cl-user(6): (getenv "FOO2")
nil
cl-user(7): (putenv "FOO2=bar2")
t
cl-user(8): (getenv "FOO2")
"bar2"
cl-user(9): (unsetenv "FOO2")
t
cl-user(10): (getenv "FOO2")
nil
cl-user(11): (setenv "FOO2" "baz" t)
     ;;; overwrite (third argument) is t so does change value
t
cl-user(12): (getenv "FOO2")
"baz"
cl-user(13): (setenv "FOO2" "bazzzzzzzz" nil) 
     ;;; overwrite (third argument) is nil so does not change value
t
cl-user(14): (getenv "FOO2")
"baz"
cl-user(15): 

The next example show how to use sys:getenv and setf to set and reset environment variables on platforms that do not have setenv.

;; The current values of the environment variable on your system may,
;; of course, be different from what appears in this example.
user(2): (sys:getenv "SHELL")
"/bin/csh"
user(3): (setf (sys:getenv "SHELL") "/bin/sh")
"/bin/sh"
user(4): (sys:getenv "SHELL")
"/bin/sh"

Warning: If you use setf with sys:getenv to set an environment variable, the string specifying the new value is stored in malloc'ed space and that space cannot be freed (in any practical way). This creates a small memory leak in the system, but it should only be significant if you set many, many environment variables.

Prior to the release of the new OSI interface mentioned above, there was no pre-defined, programmatic way to unset an environment variable from within Lisp (on those platforms which supported unsetting environment variables). With the new module, on platforms that support it, unsetenv can be used.

7.0 The Operating System Interface (OSI) module

The goal of the OSI module is to provide a Lisp layer for operating system services available on the platforms on which ACL runs. Most of the functions and macros in this module are modeled on system calls and library routines found in the UNIX manual (sections 2 and 3). The names of the functions in this module are usually the same as those found in the UNIX manual. The number and type of arguments are similar, however the interface to each system call and library routine was designed to be natural in Common Lisp so there are differences in number and type of arguments.

All of the items described here reside in the :excl.osi package. You can load it with (require :osi).

Many of the functions in this module are not available on Windows, for the simple reason that the system call or library routine is not available there. A few functions are not available on all UNIX versions on which Allegro CL runs, but most are. In all cases where a function is not available, an error of a specific type is signaled. The symbols for the functions which are not implemented are still exported from the modules' package.

Some of the functions here use system constants (e.g., R_OK). The naming of these constants is as follows: the name starts and ends with `*', has been converted to lower case, and `_' has been replaced with `-' (except leading `_'s are removed). This naming scheme is more Lisp-like and allows for the different case modes in Common Lisp.

There are a good number of system calls and library routines that take file descriptors, returned by the open() system call. In an effort to make this interface as natural in Lisp as possible, the corresponding functions in this module take a stream instead of a file descriptor. This means in general common-lisp:open should still be used to open files. However, you may want to open a file with open(2) flags for which there is no corresponding feature in Allegro CL (for example, the flag O_EXCL). For this purpose, the function os-open is provided. It also returns a stream instead of a file descriptor.

Finally, there are large number of system calls and library routines. Not all of them are implemented in this module. Some do not really make sense in Lisp, or interfere with facilities already present. One such example in the latter category is signals. All the signal calls have been left out of this interface. ACL does have a native facility for handling signals (see the function add-signal-handler).

The Shell module provides Lisp versions of various shell commands. See shell-module.htm for details.

See Appendix A Operating System Interface Functionality for a list of functions, constants, etc. in the module. Subsections, grouped by functionality, contain the documentation pages. The functions etc. (except for those which already existed) do not have individual documentation pages. They are listed in the index and the permuted index. (The constants are not indexed, however.)

7.1 System calls and library routines dealing with time

The system calls and library routines which take times take UNIX time (as described in UNIX documentation). But UNIX time and the universal time representation used by Common Lisp are different. Universal time is the number of seconds since midnight 1/1/1900, while UNIX time is the number of seconds since midnight 1/1/1970. In this module, universal times are always expected and returned, and the equivalents to the system calls and library routines which take times have been modified to expect universal times.

The functions universal-to-unix-time and unix-to-universal-time convert between UNIX and universal time. They are provided in case there is a need to communicate time values outside of Lisp. The function ctime converts a universal time to a string appropriate as an argument to certain routines.

The decision to stay with universal time in Lisp was an easy one: Common Lisp defines functions for encoding and decoding universal times (see, e.g., get-universal-time and decode-universal-time). Lisp programmers are familiar with these functions and there is no need to introduce a parallel set of functions for UNIX time manipulation.

Appendix A: Operating System Interface Functionality

The new operators, classes, and constants in the OSI module are described in the following subsections. They are grouped according to purpose (except the constants are all described in a separate document, see Appendix A.13 Lisp constants corresponding to Operating System constants). Note that they are are not indexed in the index.

Certain functions already existed (such as chdir). The symbols naming those functions have been exported from the excl.osi package as well as their home packages.

• Appendix A.1 OSI file handling functionality
• Appendix A.2 OSI time functionality
• Appendix A.3 OSI password functionality
• Appendix A.4 OSI shadow password functionality
• Appendix A.5 OSI group file access
• Appendix A.6 OSI networks file access
• Appendix A.7 OSI services file access
• Appendix A.8 OSI protocols file access
• Appendix A.9 OSI process/uid/gid interface functions
• Appendix A.10 OSI file locking functions
• Appendix A.11 OSI miscellaneous low-level functionality
• Appendix A.12 OSI miscellaneous higher-level functionality

Here is a list of operators and classes, in alphabetical order. There is also a list at the start of each subsection of the objects described in that subsection, in the order in which they appear in the subsection.

Operators

• access
• acct
• basename
• chdir
• chgrp
• chmod
• chown
• chroot
• closedir
• closelog
• command-output
• compare-files
• copy-file
• crypt
• ctermid
• ctime
• cuserid
• delete-directory-and-files
• detach-from-terminal-supported-p
• detach-from-terminal
• dirname
• endgrent
• endnetent
• endprotoent
• endpwent
• endservent
• endspent
• environment
• execve
• fchdir
• fchgrp
• fchmod
• fchown
• find-in-path
• fork
• fstat
• fsync
• get-filesystem-free-space
• getcwd
• getdomainname
• getegid
• getenv
• geteuid
• getgid
• getgrent
• getgrgid
• getgrnam
• getgroups
• gethostbyaddr
• gethostbyname
• gethostname
• getlogin
• getnetbyaddr
• getnetbyname
• getnetent
• getpgid
• getpgrp
• getpid
• getppid
• getpriority
• getprotobyname
• getprotobynumber
• getprotoent
• getpwent
• getpwnam
• getpwuid
• getservbyname
• getservbyport
• getservent
• getsid
• getspent
• getspnam
• getuid
• grent-gid
• grent-mem
• grent-name
• grent-p
• grent-passwd
• htonl
• htons
• initgroups
• isatty
• kill
• lchown
• link
• lock-stream
• lockf
• locking
• lstat
• mkdir
• mkdtemp
• mkstemp
• netent-addrtype
• netent-aliases
• netent-name
• netent-net
• netent-p
• ntohl
• ntohs
• opendir
• openlog
• os-close
• os-ftruncate
• os-open
• os-remove
• os-truncate
• perror
• pipe
• protoent-aliases
• protoent-name
• protoent-p
• protoent-proto
• putenv
• pwent-dir
• pwent-gcos
• pwent-gid
• pwent-name
• pwent-p
• pwent-passwd
• pwent-shell
• pwent-uid
• readdir
• readlink
• realpath
• rename
• rmdir
• same-file-p
• same-filesystem-p
• servent-aliases
• servent-name
• servent-p
• servent-port
• servent-proto
• setegid
• setenv
• seteuid
• setgid
• setgrent
• setgroups
• setnetent
• setpgid
• setpgrp
• setpriority
• setprotoent
• setpwent
• setregid
• setreuid
• setservent
• setsid
• setspent
• setuid
• shadow-passwd-supported-p
• spwd-expire
• spwd-inact
• spwd-last-change
• spwd-max
• spwd-min
• spwd-name
• spwd-p
• spwd-passwd
• spwd-warn
• stat-atime
• stat-ctime
• stat-dev
• stat-gid
• stat-ino
• stat-mode
• stat-mtime
• stat-nlink
• stat-rdev
• stat-size
• stat-type
• stat-uid
• stat
• strerror
• symlink
• sync
• syscall-error-errno
• syslog
• ttyname
• umask
• universal-to-unix-time
• unix-to-universal-time
• unlink
• unlock-stream
• unsetenv
• utime
• wait
• waitpid
• with-command-io
• with-command-output
• with-open-temp-file
• with-os-open-file
• with-pipe
• with-stream-lock

Classes

• osi-not-supported
• syscall-error

Constants

We have provided Lisp constants corresponding to the various operating system constants. The Lisp constants typically provide default values for various arguments. See Appendix A.13 Lisp constants corresponding to Operating System constants and the separate document osi-constants.htm for a complete list of such constants. Note that not every constant is defined on every platform (architecture). In each definition, we say what platforms the constant is defined on. Then in Defined Operating System/Lisp constants by architecture in osi-constants.htm, we provide a list by platform of defined constants. We do not describe how the constants are used. Please look at the appropriate Operating System documentation for information on how these constants are used. (The operating system name, which differs from the Lisp name, is shown in each definition. You can search by the operating system name to find the corresponding Lisp name, if there is one.)

In an earlier version of the documentation, we did not name all defined constants and we mixed definitions of constants we did name with the related operators. In this version, we list all constants together, and list them all.

Appendix A.1 OSI file handling functionality

• os-truncate
• os-ftruncate
• utime
• mkdir
• rmdir
• delete-directory-and-files
• unlink
• os-remove
• rename
• link
• symlink
• readlink
• stat
• stat-atime
• stat-ctime
• stat-dev
• stat-gid
• stat-ino
• stat-mode
• stat-mtime
• stat-nlink
• stat-rdev
• stat-size
• stat-type
• stat-uid
• fstat
• lstat
• chmod
• fchmod
• chown
• fchown
• lchown
• chgrp
• fchgrp
• access
• opendir
• closedir
• readdir
• fsync
• mkdtemp
• mkstemp
• with-open-temp-file
• basename
• dirname
• chdir
• fchdir
• getcwd
• realpath
• copy-file
• os-close
• os-open
• with-os-open-file
• get-filesystem-free-space

os-truncate

Function

Package: excl.osi

Arguments: filespec length

Truncate filespec to at most length bytes in size. Returns t on success, and signals an error of type syscall-error on failure. See the UNIX man page truncate(2) for more information.

os-ftruncate

Function

Package: excl.osi

Arguments: stream length

Truncate the file pointed to by stream to at most length bytes in size. Returns t on success, and signals an error of type syscall-error on failure. See the UNIX man page ftruncate(2) for more information.

utime

Function

Package: excl.osi

Arguments: filespec atime mtime

Change the access and modification times on filespec to those given by atime (for access) and/or mtime (for modification). At least one of atime and mtime should be a universal time. The other can also be a universal time or nil (in which case that time is not set). utime returns t on success, and signals an error of type syscall-error on failure. See the UNIX man page utime(2) for more information.

For information on conversion to/from universal and UNIX time see unix-to-universal-time and universal-to-unix-time.

See also file-access-date.

mkdir

Function

Package: excl.osi

Arguments: filespec &key all mode

Make the directory given by filespec, and if the keyword argument all is non-nil make all parent directories which do not exist.

If mode is non-nil it should be a numeric mode for the creation of filespec.

rmdir

Function

Package: excl.osi

Arguments: filespec &key force

Delete the directory given by filespec. On Windows, the force keyword can be used to remove filespec when it is read-only. On UNIX, this is the default behavior so force is effectively ignored.

delete-directory-and-files

Function

Package: excl

Arguments: directory &key (if-does-not-exist :error) (quiet t) force

Delete all the files and subdirectories in the directory given by directory and then delete the directory itself. On Windows, the force keyword can be used to remove filespec when it is read-only. On UNIX, this is the default behavior so force is effectively ignored.

The symbol naming this function is in the excl package and exported from the excl.osi package. This function was defined in Allegro CL prior to the release of the :osi module (though the force argument was added with the release of the :osi module). Its manual page is here. The keywords arguments are fully described on that page.

unlink

Function

Package: excl.osi

Arguments: filespec &key force

Delete filespec from the filesystem. On Windows, the force keyword can be used to remove filespec when it is read-only. On UNIX, this is the default behavior so force is effectively ignored. Returns t on success, and signals an error of type syscall-error on failure. See the UNIX man page unlink(2) for more information.

os-remove

Function

Package: excl.osi

Arguments: filespec &key force

Delete filespec from the filesystem. It calls unlink for files and rmdir for directories. On Windows, the force keyword can be used to remove filespec when it is read-only. On UNIX, this is the default behavior so force is effectively ignored. Returns t on success, and signals an error of type syscall-error on failure.

rename

Function

Package: excl.osi

Arguments: from-filespec to-filespec

Rename from-filespec to to-filespec. On success t is returned. On failure an error of type syscall-error is signaled. For a description of the specific behavior of this system call, see the documentation for rename(2) on UNIX and _rename on Windows.

link

Function

Package: excl.osi

Arguments: old-filespec new-filespec

Create a new link (also known as a hard link) to an existing file. If new-filespec exists it will not be overwritten. Returns t on success, and signals an error of type syscall-error on failure. See the UNIX man page link(2) for more information.

The function symlink can be used to create symbolic links.

This function is not supported on Windows, where it signals an error of class osi-not-supported.

symlink

Function

Package: excl.osi

Arguments: old new &key raw

Create a new symbolic link to an existing file. This function is not supported on Windows, where it signals an error. If raw is non-nil, then the required arguments must be strings. This prevents pathname merging, which could turn a relative filename into an absolute one, and is required if relative symbolic links are desired. Returns t on success, and signals an error of type syscall-error on failure.

See the UNIX man page link(2) for more information.

The function link can be used to create hard links.

readlink

Function

Package: excl.osi

Arguments: filespec

Return the contents of a symbolic link given by filespec. On failure an error of type syscall-error is signaled.

This function is not supported on Windows, where it signals an error of class osi-not-supported.

stat

Function

Package: excl.osi

Arguments: filespec

Return information about the specified file, filespec. The accessor functions stat-dev, stat-ino, stat-mode, stat-nlink, stat-uid, stat-gid, stat-rdev, stat-size, stat-atime, stat-ctime and stat-mtime can be used to retrieve specific information from the value returned by this function. On failure an error of type syscall-error is signaled.

NOTE: the values returned by stat-atime, stat-ctime and stat-mtime are universal times and not UNIX times. For information on conversion to/from universal and UNIX time see unix-to-universal-time and universal-to-unix-time. See Section 7.1 System calls and library routines dealing with time

stat-atime

Function

Package: excl.osi

Arguments: f

Accessor for the value returned by stat.

NOTE: the values returned by stat-atime, stat-ctime and stat-mtime are universal times and not UNIX times. For information on conversion to/from universal and UNIX time see unix-to-universal-time and universal-to-unix-time. See Section 7.1 System calls and library routines dealing with time

stat-ctime

Function

Package: excl.osi

Arguments: f

Accessor for the value returned by stat.

NOTE: the values returned by stat-atime, stat-ctime and stat-mtime are universal times and not UNIX times. For information on conversion to/from universal and UNIX time see unix-to-universal-time and universal-to-unix-time. See Section 7.1 System calls and library routines dealing with time

stat-dev

Function

Package: excl.osi

Arguments: f

Accessor for the value returned by stat.

stat-gid

Function

Package: excl.osi

Arguments: f

Accessor for the value returned by stat.

stat-ino

Function

Package: excl.osi

Arguments: f

Accessor for the value returned by stat.

stat-mode

Function

Package: excl.osi

Arguments: f

Accessor for the value returned by stat.

stat-mtime

Function

Package: excl.osi

Arguments: f

Accessor for the value returned by stat.

NOTE: the values returned by stat-atime, stat-ctime and stat-mtime are universal times and not UNIX times. For information on conversion to/from universal and UNIX time see unix-to-universal-time and universal-to-unix-time. See Section 7.1 System calls and library routines dealing with time

stat-nlink

Function

Package: excl.osi

Arguments: f

Accessor for the value returned by stat.

stat-rdev

Function

Package: excl.osi

Arguments: f

Accessor for the value returned by stat.

stat-size

Function

Package: excl.osi

Arguments: f

Accessor for the value returned by stat.

stat-type

Function

Package: excl.osi

Arguments: stat

Given the value returned by stat, fstat or lstat, return a keyword describing the type of file object, one of: :file, :directory, :fifo, :character-device, :symbolic-link, :socket, :block-device, or :unknown. :symbolic-link, :socket and :block-device are never returned on Windows.

stat-uid

Function

Package: excl.osi

Arguments: f

Accessor for the value returned by stat.

fstat

Function

Package: excl.osi

Arguments: stream

This function is just like the function stat except that it operates on an open stream.

lstat

Function

Package: excl.osi

Arguments: filespec

This function is just like the function stat except that it operates on a symbolic link itself rather than the file to which the symbolic links points.

This function is not supported on Windows, where it signals an error of class osi-not-supported.

chmod

Function

Package: excl.osi

Arguments: filespec mode

Change the mode of filespec to mode. mode should be a number, and it is convenient to specify it as a three digit octal number (#o755 for `rwxr-xr-x'). Consult the Windows documentation for the precise meaning of mode on Windows.

fchmod

Function

Package: excl.osi

Arguments: stream mode

Change the mode of the file given by the open stream stream to mode. mode should be a number, and it is convenient to specify it as a three digit octal number (#o755 for `rwxr-xr-x'). Consult the Windows documentation for the precise meaning of mode on Windows.

chown

Function

Package: excl.osi

Arguments: filespec owner &optional group

Change the owner of filespec to owner, also changing the group if that optional argument is provided. On success t is returned. On failure an error of type syscall-error is signaled.

owner can be either a number representing a UID or a string naming a user. In the case of a string naming a user, that user is looked up with getpwnam and the resulting UID is taken from that.

group can be either a number representing a GID or a string naming a group In the case of a string naming a group, that group is looked up with getgrnam and the resulting GID is taken from that.

This function is not supported on Windows, where it signals an error of class osi-not-supported.

fchown

Function

Package: excl.osi

Arguments: stream owner &optional group

Change the owner of the file given by the open stream stream to owner, also changing the group if that optional argument is provided. On success t is returned. On failure an error of type syscall-error is signaled.

owner can be either a number representing a UID or a string naming a user. In the case of a string naming a user, that user is looked up with getpwnam and the resulting UID is taken from that.

group can be either a number representing a GID or a string naming a group In the case of a string naming a group, that group is looked up with getgrnam and the resulting GID is taken from that.

This function is not supported on Windows, where it signals an error of class osi-not-supported.

lchown

Function

Package: excl.osi

Arguments: filespec owner &optional group

Change the owner of the symbolic link given by filespec to owner, also changing the group if that optional argument is provided. On success t is returned. On failure an error of type syscall-error is signaled.

owner can be either a number representing a UID or a string naming a user. In the case of a string naming a user, that user is looked up with getpwnam and the resulting UID is taken from that.

group can be either a number representing a GID or a string naming a group In the case of a string naming a group, that group is looked up with getgrnam and the resulting GID is taken from that.

This function is not supported on Windows, where it signals an error of class osi-not-supported.

chgrp

Function

Package: excl.osi

Arguments: filespec group &optional owner

Change the group of filespec to group, also changing the owner if that optional argument is provided. On success t is returned. On failure an error of type syscall-error is signaled.

group can be either a number representing a GID or a string naming a group In the case of a string naming a group, that group is looked up with getgrnam and the resulting GID is taken from that.

owner can be either a number representing a UID or a string naming a user. In the case of a string naming a user, that user is looked up with getpwnam and the resulting UID is taken from that.

This function is not supported on Windows, where it signals an error of class osi-not-supported.

fchgrp

Function

Package: excl.osi

Arguments: stream group &optional owner

Change the group of the file given by the open stream stream to group, also changing the owner if that optional argument is provided. On success t is returned. On failure an error of type syscall-error is signaled.

group can be either a number representing a GID or a string naming a group In the case of a string naming a group, that group is looked up with getgrnam and the resulting GID is taken from that.

owner can be either a number representing a UID or a string naming a user. In the case of a string naming a user, that user is looked up with getpwnam and the resulting UID is taken from that.

This function is not supported on Windows, where it signals an error of class osi-not-supported.

access

Function

Package: excl.osi

Arguments: filespec mode &key error

Test for permissions on filespec using mask mode. If the specified permissions exist, then t is returned and nil otherwise. On failure, signal an error of type syscall-error if error is non-nil, or return nil otherwise. The default value of error is nil.

Failure means the system function access(2) returned -1. That might have happened, for example, if access to one of the directories in the path of filespec was denied.

mode is composed from the bitwise or'ing of the constants *r-ok*, *w-ok*, *f-ok*, and *x-ok*, which correspond to the C definitions of R_OK, W_OK, F_OK and X_OK. *x-ok* is not defined on Windows, since it has no meaning there.

opendir

Function

Package: excl.osi

Arguments: filespec

Open the directory given my filespec and return a handle for further operations on it. On failure signal an error of type syscall-error.

closedir

Function

Package: excl.osi

Arguments: dir

Close the directory handle associated with dir. On failure signal an error of type syscall-error.

readdir

Function

Package: excl.osi

Arguments: dir

Return the string representing the next directory entry in the directory stream pointed to by dir. On failure signal an error of type syscall-error.

fsync

Function

Package: excl.osi

Arguments: stream

Synchronize the in-core parts of a file to disk. For more information on this UNIX system call see the fsync(2) manual page.

This function is not supported on Windows, where it signals an error of class osi-not-supported.

mkdtemp

Function

Package: excl.osi

Arguments: template

This function was added in an update released in mid-January 2008. This function will not be available if you do not have the update. See sys:update-allegro for information on getting updates.

This function is not supported on Windows, Solaris or HP-UX. Calling it on those platform signals an error of type osi-not-supported.

This function creates a temporary directory and returns the name of the directory created (a string). The name of the file is determined by the template specified by template. template should end with six X's, which are replaced with a unique letter combination.

On failure an error of type syscall-error is signaled.

See the UNIX man page for mkdtemp(3) for more information on the system call associated with this function. It will tell you about things like the permissions on the new directory. The input string (template) is not modified and shares no space with the output string naming the new directory, which will be a newly-created string.

See also Section 4.0 Temporary directory and files.

Example

;; We create a suitable string to use as the template:
cl-user(2): (setq dir-template "/tmp/testXXXXXX")
"/tmp/testXXXXXX"

;; The call to EXCL.OSI:MKDTEMP returns the new directory name:
cl-user(3): (setq dir-result-1 (excl.osi:mkdtemp dir-template))
"/tmp/testUTxnSF"

;; This shows the new directory exists:
cl-user(4): (probe-file dir-result-1)
#P"/tmp/testUTxnSF"

;; The input template and the output name are not the same string:
cl-user(5): (eq dir-template dir-result-1)
nil

;; And the input string is unchanged:
cl-user(6): dir-template
"/tmp/testXXXXXX"

;; We use it again and get a different name:
cl-user(7): (setq dir-result-2 (excl.osi:mkdtemp dir-template))
"/tmp/testMaM3dH"

;; The string holding the first directory name is unaffected by 
;; subsequent calls:
cl-user(8): dir-result-1
"/tmp/testUTxnSF"
cl-user(9): 

mkstemp

Function

Package: excl.osi

Arguments: template

This function opens (for output) a stream on a temporary file and returns two values: the stream and the name of the file. The name of the file is determined by the template specified by template. template should end with six X's, which are replaced with the current process number and/or a unique letter combination. mkstemp, like the UNIX counterpart, is free of race conditions on opening the file.

On failure an error of type syscall-error is signaled.

This function is not supported on Windows, where it signals an error of class osi-not-supported.

See also with-open-temp-file, mkdtemp, and Section 4.0 Temporary directory and files.

with-open-temp-file

Macro

Package: excl.osi

Arguments: (var template &key filename delete) &body body

This macro allows for safe use of temporary files, making sure they are closed in the face of errors. It is also good for making sure there are no race conditions on opening the file in the filesystem.

var should be a symbol which will by bound to the stream open to the file during the evaluation of body. The argument template is passed to mkstemp and should be a value suitable for the template argument to that function, that is a string ending in six X's. The beginning of the string (up to the X's) should be directory information plus whatever you want as the beginning of the temp file name, for example "/tmp/mytempXXXXXX".

The filename keyword argument, when supplied, must be a symbol. The symbol will be bound during the evaluation of the body to the actual filename that is used. The delete keyword argument, if supplied and non-nil, causes the file to be deleted after the body completes (either normally or abnormally). Any errors that may occur during file deletion are ignored.

The name of the temp file actually used is returned after body completes. The file is not deleted automatically after this macro completes unless delete is specified true. Here are a couple of examples:

cl-user(31): (excl.osi:with-open-temp-file (ss "/tmp/mytempXXXXXX") 
                    (print 10 ss))
"/tmp/mytempRQaWrj"
cl-user(32): (shell "cat /tmp/mytempRQaWrj")

10 0
cl-user(33): (excl.osi:with-open-temp-file (ss "/tmp/mytempXXXXXX")
	       (print 10 ss)
	       (file-position ss 0)
	       (setq a (read ss)))
"/tmp/mytempSQaWrj"
cl-user(34): a
10
cl-user(35): 

Because this macro uses mkstemp (which is not available on Windows), this macro is not supported on Windows.

basename

Function

Package: excl.osi

Arguments: filespec

Break filespec into directory and filename components, returning the filename component. This is equivalent to

(file-namestring (pathname filespec))

dirname

Function

Package: excl.osi

Arguments: filespec &optional trailing-slash

Break filespec into directory and filename components, returning the directory component. The library routine dirname(3) does not return a trailing slash, however this behavior is problematic when considering Common Lisp pathnames--converting the result, without a trailing slash, to a pathname will yield unexpected results. The optional second argument, trailing-slash, is meant to deal with this problem. The default value is t, which means the non-dirname(3) behavior is the default. Examples:

(dirname "/foo/bar/baz")
  RETURNS "/foo/bar/"
(dirname "/foo/bar/baz" nil)
  RETURNS "/foo/bar"
(pathname-directory (dirname "/foo/bar/baz"))
  RETURNS (:absolute "foo" "bar")
(pathname-directory (dirname "/foo/bar/baz" nil))
  RETURNS (:absolute "foo")
(pathname-name (dirname "/foo/bar/baz" nil))
  RETURNS "bar"

On Windows, drive and share names are considered part of the directory component.

chdir

Function

Package: excl

Arguments: &optional directory

Change the current working directory to the directory given by the directory argument. If no directory is given, change to the user's home directory. On success a string representing the new current working directory is returned. On failure an error of type syscall-error is signaled.

chdir does not change *default-pathname-defaults*.

The symbol naming this function is in the excl package and exported from the excl.osi package. This function was defined in Allegro CL prior to the release of the :osi module. Its manual page is here.

fchdir

Function

Package: excl.osi

Arguments: stream

Change the current working directory to the directory given by the stream argument. (fchdir stream) is equivalent to:

(chdir (dirname stream))

See chdir. Note that chdir (and thus fchdir) do not change *default-pathname-defaults*.

getcwd

Function

Package: excl.osi

Arguments:

Return the current working directory as a pathname. This function is the same as current-directory.

realpath

Function

Package: excl.osi

Arguments: filespec

Return a pathname which is the canonicalized form of filespec. On failure an error of type syscall-error is signaled. See the UNIX manual page for realpath(3) for more information on how filespec is canonicalized.

This function is not supported on Windows, where it signals an error of class osi-not-supported.

copy-file

Function

Package: system

Arguments: from-pathname to-pathname &key link overwrite preserve-symbolic-links preserve-time remove-destination force

Copy from-pathname to to-pathname. The keyword arguments specify how to handle particular situations and how to handle links.

The symbol naming this function is in the system package and exported from the excl.osi package. This function was defined in Allegro CL prior to the release of the :osi module (though the remove-destination and force keyword arguments were added with the release of the :osi module). Its manual page is here. The keywords arguments are fully described on that page.

os-open

Function

Package: excl.osi

Arguments: filespec flags &optional mode

Open filespec for reading, writing or both. The flags and mode arguments are defined by the open(2) system call documentation on each system. The value returned, if successful, is a Common Lisp stream. On failure an error of type syscall-error is signaled.

The utility of os-open is for being able to use open(2) flags for which there is no corresponding feature in Allegro. O_EXCL is a good example of such a flag. Be aware that using system specific flags will make your programs non-portable. Consult the operating system documentation on the systems you care about to make sure the flags in question exist on those platforms.

See with-os-open-file, which is a cl:with-open-file analog using os-open instead of cl:open to open the file.

with-os-open-file

Macro

Package: excl.osi

Arguments: (var &rest rest os-open-args) &body body

This macro works like cl:with-open-file except it uses os-open instead of cl:open to open the file. It binds var to a stream returned by os-open, executes body and then closes the stream. This macro makes sure the stream is closed when the body exits, regardless of whether the exit is normal or non-local (i.e. caused by a throw or an error). os-open-args are given directly to os-open.

This macro was added to a module in a patch released around April 4, 2003. You must have updated (using sys:update-allegro) after that date for this macro to be defined.

os-close

Function

Package: excl.osi

Arguments: stream

The same as common-lisp:close, provided for symmetry with os-open. (excl.osi:os-close stream) is the same as (cl:close stream).

get-filesystem-free-space

Function

Package: excl.osi

Arguments: filespec

get-filesystem-free-space returns three values indicating space information about the filesystem on which `filespec' resides.

• available: The number of free bytes that are available to the user making the call.
• total-free: The number of free bytes in the filesystem.
• total-size: The size of the filesystem (in bytes).

For various reasons, it is not unusual for 'available' to be less than 'total-free'. For example, if filesystem quotas are in place, 'available' will indicate the amount remaining in your quota. On Unix filesystems, it is common to reserve a portion of free space such that it can only be used by the root user. In those cases, 'available' will report the free space available to non-root users and 'total-free' will report the free space available to root.

Appendix A.2 OSI time functionality

• universal-to-unix-time
• unix-to-universal-time
• ctime

universal-to-unix-time

Function

Package: excl.osi

Arguments: universal-time

Convert the argument universal-time to a UNIX time. See Section 7.1 System calls and library routines dealing with time for more information. See also unix-to-universal-time.

unix-to-universal-time

Function

Package: excl.osi

Arguments: unix-time

Convert the argument unix-time to a universal time. See Section 7.1 System calls and library routines dealing with time for more information. See also universal-to-unix-time.

ctime

Function

Package: excl.osi

Arguments: &optional ut

Return a string containing the time as of ut (which is a universal time) in the same format as the UNIX library routine ctime(3). In ACL, this is:

(locale-print-time ut :fmt "%a %b %d %T %Y")

Here are a couple of examples. They indicate that ut defaults to the current time, as returned by get-universal-time (the times differ by a few seconds because they were run sequentially).

cl-user(2): (excl.osi:ctime)
"Thu Oct 24 10:11:30 2002"
cl-user(3): (excl.osi:ctime (get-universal-time))
"Thu Oct 24 10:11:36 2002"
cl-user(4): 

See Section 7.1 System calls and library routines dealing with time for more information.

Appendix A.3 OSI password functionality

• setpwent
• endpwent
• getpwent
• getpwnam
• getpwuid
• pwent-p
• pwent-dir
• pwent-gcos
• pwent-gid
• pwent-name
• pwent-passwd
• pwent-shell
• pwent-uid

setpwent

Function

Package: excl.osi

Arguments: &rest args

This function rewinds the file pointer to the beginning of the /etc/passwd file so getpwent can be used to iterate over all the entries.

endpwent

Function

Package: excl.osi

Arguments: &rest args

This function closes the /etc/passwd file. See getpwent.

getpwent

Function

Package: excl.osi

Arguments:

Return a pwent (i.e. password entry) structure corrsponding to the current entry in the file /etc/passwd. The pwent accessors are used to extract values from the structure, and the functions setpwent and endpwent are used to open and close the passwd file. See the Operating System documentation about passwords for details of the pwent structures and the specifics of this and related functions.

pwent-p returns true if its argument is a pwent structure. pwent structures have the following accessors:

• pwent-dir
• pwent-gcos
• pwent-gid
• pwent-name
• pwent-passwd
• pwent-shell
• pwent-uid

The pwent functions are only available on UNIX.

getpwnam

Function

Package: excl.osi

Arguments: name

Get a pwent structure by name. See getpwent.

getpwuid

Function

Package: excl.osi

Arguments: uid

Get a pwent structure by uid. See getpwent.

pwent-p

Function

Package: excl.osi

Arguments: object

Return t if the argument is a pwent, nil otherwise. See getpwent.

pwent-dir

Function

Package: excl.osi

Arguments: struct

Accessor for the pwent type. See getpwent.

pwent-gcos

Function

Package: excl.osi

Arguments: struct

Accessor for the pwent type. See getpwent.

pwent-gid

Function

Package: excl.osi

Arguments: struct

Accessor for the pwent type. See getpwent.

pwent-name

Function

Package: excl.osi

Arguments: pwent

Accessor for the pwent type. See getpwent.

pwent-passwd

Function

Package: excl.osi

Arguments: pwent

Accessor for the pwent type. See getpwent.

pwent-shell

Function

Package: excl.osi

Arguments: pwent

Accessor for the pwent type. See getpwent.

pwent-uid

Function

Package: excl.osi

Arguments: pwent

Accessor for the pwent type. See getpwent.

Appendix A.4 OSI shadow password functionality

• shadow-passwd-supported-p
• setspent
• endspent
• getspent
• getspnam
• spwd-p
• spwd-expire
• spwd-inact
• spwd-last-change
• spwd-max
• spwd-min
• spwd-name
• spwd-passwd
• spwd-warn

shadow-passwd-supported-p

Function

Package: excl.osi

Arguments:

Return t if shadow passwd support is available on this version of Lisp.

setspent

Function

Package: excl.osi

Arguments: &rest args

This function rewinds the file pointer to the beginning of the shadow passwd file so getspent can be used to iterate over all the entries.

endspent

Function

Package: excl.osi

Arguments: &rest args

This function closes the shadow passwd file. See getspent and setspent.

getspent

Function

Package: excl.osi

Arguments:

Return a spwd (i.e. shadow password) structure corrsponding to the current entry in the shadow passwd file. The spwd accessors are used to extract values from the structure, and the functions setspent and endspent are used to open and close the shadow passwd file.

spwd-p returns true if its argument is a spwd structure. The accessors for spwd structures are:

• spwd-expire
• spwd-inact
• spwd-last-change
• spwd-max
• spwd-min
• spwd-name
• spwd-passwd
• spwd-warn

The spwd functions are only available on some versions of UNIX.

getspnam

Function

Package: excl.osi

Arguments: name

Get a spwd structure by name. See getspent.

spwd-p

Function

Package: excl.osi

Arguments: object

Return t if the argument is a spwd, nil otherwise. See getspent.

spwd-expire

Function

Package: excl.osi

Arguments: spwd

Accessor for the spwd type. See getspent.

spwd-inact

Function

Package: excl.osi

Arguments: spwd

Accessor for the spwd type. See getspent.

spwd-last-change

Function

Package: excl.osi

Arguments: spwd

Accessor for the spwd type. See getspent.

spwd-max

Function

Package: excl.osi

Arguments: spwd

Accessor for the spwd type. See getspent.

spwd-min

Function

Package: excl.osi

Arguments: spwd

Accessor for the spwd type. See getspent.

spwd-name

Function

Package: excl.osi

Arguments: spwd

Accessor for the spwd type. See getspent.

spwd-passwd

Function

Package: excl.osi

Arguments: spwd

Accessor for the spwd type. See getspent.

spwd-warn

Function

Package: excl.osi

Arguments: spwd

Accessor for the spwd type. See getspent.

Appendix A.5 OSI group file access

• setgrent
• endgrent
• getgrent
• grent-p
• grent-gid
• grent-mem
• grent-name
• grent-passwd
• getgrnam
• getgrgid

setgrent

Function

Package: excl.osi

Arguments: &rest args

This function rewinds the file pointer to the beginning of /etc/group so getgrent can be used to iterate over all the entries.

endgrent

Function

Package: excl.osi

Arguments: &rest args

This function closes the group file. See getgrent.

getgrent

Function

Package: excl.osi

Arguments:

Return a grent structure corrsponding to the current entry in the file /etc/group. The grent accessors are used to extract values from the structure, and the functions setgrent and endgrent are used to open and close the group file.

grent-p returns true if its argument is a grent structure. The accessors for grent structures are:

• grent-gid
• grent-mem
• grent-name
• grent-passwd

This grent functions are only available on UNIX.

grent-p

Function

Package: excl.osi

Arguments: object

Return t if the argument is a grent, nil otherwise. See getgrent.

grent-gid

Function

Package: excl.osi

Arguments: gid

Accessor for the grent type. See getgrent.

grent-mem

Function

Package: excl.osi

Arguments: gid

Accessor for the grent type. See getgrent.

grent-name

Function

Package: excl.osi

Arguments: gid

Accessor for the grent type. See getgrent.

grent-passwd

Function

Package: excl.osi

Arguments: gid

Accessor for the grent type. See getgrent.

getgrnam

Function

Package: excl.osi

Arguments: name

Get a grent structure by name. See getgrent.

getgrgid

Function

Package: excl.osi

Arguments: gid

Get a grent structure by uid. See getgrent.

Appendix A.6 OSI networks file access

• setnetent
• endnetent
• getnetent
• netent-p
• netent-addrtype
• netent-aliases
• netent-name
• netent-net
• getnetbyname
• getnetbyaddr
• setservent

setnetent

Function

Package: excl.osi

Arguments: &optional stay-open

This function rewinds the file pointer to the beginning of /etc/networks so getnetent</