ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Moderately revised from 8.2. 8.2 version

# Operating System Interface

This document contains the following sections:

1.0 Operating-system interface
2.0 Subprocess functions
3.0 Filesystem manipulation functions
4.0 Temporary directory and files
5.0 Accessing command-line arguments
6.0 Polling and setting environment variables
7.0 The Operating System Interface (OSI) module
7.1 System calls and library routines dealing with time
Appendix A. Operating System Interface Functionality
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
Appendix A.13. Lisp constants corresponding to Operating System constants

## 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:

Name | Arguments | Notes
chdir | &optional pathname | Make pathname the current directory. If unspecified, make the current user's home directory the current directory (UNIX) or make c:\ the current directory (Windows). See the full description as the function has some oddities. See also the example below.
current-directory |  | Returns the current directory.
getcwd |  | Another name for current-directory. Added with the new OSI interface (see Section 7.0 The Operating System Interface (OSI) module). See Appendix A.1 OSI file handling functionality for descriptions of all the new functionality relevant to this section. Returns the current directory.
username-to-home-directory | name | On Unix, returns the home directory of the user named by the argument. On Windows, uses the value of the `HOME` environment variable; uses `C:\\` if that variable is not set.

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.

Function | Arguments | Notes
excl:copy-directory | from-dir to-dir &key quiet &allow-other-keys | Copies from-dir to to-dir. Accepts sys:copy-file keywords for copying files in the directory being copied.
sys:copy-file | from-pathname to-pathname &key link preserve-symbolic-links element-type preserve-time remove-destination force | Copies from-pathname to to-pathname preserving features as specified by keyword arguments. Note: link argument was called link-ok in releases 5.0.1 and earlier. See also the other functions in the new `:osi` module associated with filesystem manipulation, described in Appendix A.1 OSI file handling functionality.
excl:delete-directory | pathname | Deletes the directory named by pathname, which must be an empty directory. See also the new function rmdir and other functions in the new `:osi` module associated with filesystem manipulation, described in Appendix A.1 OSI file handling functionality.
excl:delete-directory-and-files | directory &key if-does-not-exist quiet force | Deletes the directory named by directory and all of its subdirectories and files. See also the new functions in the new `:osi` module associated with filesystem manipulation, described in Appendix A.1 OSI file handling functionality.
excl:directory-size | dirname &key roundup | Returns the size in bytes of all the files in the directory named by dirname and all its subdirectories. If roundup is non-`nil`, its value must be an integer, and the result will be rounded up to a multiple of that integer.
excl:file-directory-p | filespec | Returns true if argument names a directory.
excl:make-directory | pathname &optional mode | Creates a directory named by pathname.
excl:map-over-directory | function directory &key filter prune-directories include-directories file-type recurse | Applies function to the entries in directory, with keywords allowing for finer control.

## 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.

Name | Arguments | Notes
system:temporary-directory |  | Returns the pathname of the temporary directory used by the current running Lisp for writing temporary files.
system:make-temp-file-name | &optional (prefix "temp") (directory(sys:temporary-directory)) | Returns an unused filename but does not create the file (so the same name could be returned by a subsequent call if the file is not created).
mkstemp | template | Like system:make-temp-file-name except it opens the file for output and returns the stream (rather than the filename). This operator is part of the new the new OSI interface (see Section 7.0 The Operating System Interface (OSI) module).
with-open-temp-file | (var template) &body body | Opens a temporary file named according to template while body is evaluated, and returns the name of the (now closed) file. This operator is part of the new the new OSI interface (see Section 7.0 The Operating System Interface (OSI) module).

## 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.

Name | Arguments | Notes
system:command-line-argument | (n &key application) | Returns the value of the nth command-line arguments.
system:command-line-arguments | (&key application) | Returns a list of all command-line arguments.
system:command-line-argument-count | (&key application) | Returns the number of command-line arguments.

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
- fdatasync
- fsync
- get-filesystem-free-space
- get-mem-info
- 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
- strsignal
- symlink
- sync
- syscall-error-errno
- sysconf
- 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
- fdatasync
- 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`.

### fdatasync

### 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. On success `t` is returned. 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`.

### 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 is not supported on Windows, or Solaris. 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. The name ends with a trailing slash.

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 &key (external-format :default)

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.

The external-format keyword can be used to change the default external-format used to open the stream.

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 external-format) &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. If an error occurs during the execution of body then the open stream on the temporary file is closed with `:abort t` given to common-lisp:close.

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 can be used to iterate over all the entries. The argument stay-open is non-`nil`, then the file will not be closed between calls to getnetbyname and getnetbyaddr.

### endnetent

### Function

#### Package: excl.osi

Arguments: &rest args

This function closes the networks file. See getnetent.

### getnetent

### Function

#### Package: excl.osi

Arguments:

Return a netent structure corrsponding to the current entry in the file /etc/networks. The netent accessors are used to extract values from the structure, and the functions setnetent and endnetent are used to open and close the networks file.

netent-p returns true if its argument is a netent structure. The netent accessors are:

- netent-addrtype
- netent-aliases
- netent-name
- netent-net

The netent functions are only available on UNIX.

### netent-p

### Function

#### Package: excl.osi

Arguments: object

Return `t` if the argument is a netent, `nil` otherwise. See getnetent.

### netent-addrtype

### Function

#### Package: excl.osi

Arguments: netent

Accessor for the netent type. See getnetent.

### netent-aliases

### Function

#### Package: excl.osi

Arguments: netent

Accessor for the netent type. See getnetent.

Arguments:

### netent-name

### Function

#### Package: excl.osi

Arguments: netent

Accessor for the netent type. See getnetent.

### netent-net

### Function

#### Package: excl.osi

Arguments: netent

Accessor for the netent type. See getnetent.

### getnetbyname

### Function

#### Package: excl.osi

Arguments: name

Get a netent structure by name. See getnetent.

### getnetbyaddr

### Function

#### Package: excl.osi

Arguments: net type

Get a netent structure by address and type. See getnetent.

## Appendix A.7 OSI services file access

- endservent
- getservent
- servent-p
- servent-aliases
- servent-name
- servent-port
- servent-proto
- getservbyname
- getservbyport

### setservent

### Function

#### Package: excl.osi

Arguments: &optional stay-open

This function rewinds the file pointer to the beginning of /etc/services so getservent can be used to iterate over all the entries. The argument stay-open is non-`nil`, then the file will not be closed between calls to getservbyname and getservbyport.

### endservent

### Function

#### Package: excl.osi

Arguments: &rest args

This function closes the services file. See getservent.

### getservent

### Function

#### Package: excl.osi

Arguments:

Return a servent structure corrsponding to the current entry in the file /etc/services. The servent accessors are used to extract values from the structure, and the functions setservent and endservent are used to open and close the services file.

servent-p returns true if its argument is a servent structure. The servent accessors are:

- servent-aliases
- servent-name
- servent-port
- servent-proto

The servent functions are only available on UNIX.

### servent-p

### Function

#### Package: excl.osi

Arguments: object

Return `t` if the argument is a servent, `nil` otherwise. See getservent.

### servent-aliases

### Function

#### Package: excl.osi

Arguments: servent

Accessor for the servent type. See getservent.

### servent-name

### Function

#### Package: excl.osi

Arguments: servent

Accessor for the servent type. See getservent.

### servent-port

### Function

#### Package: excl.osi

Arguments: servent

Accessor for the servent type. See getservent.

### servent-proto

### Function

#### Package: excl.osi

Arguments: servent

Accessor for the servent type. See getservent.

### getservbyname

### Function

#### Package: excl.osi

Arguments: name proto

Get a servent structure by name and protocol. See getservent.

### getservbyport

### Function

#### Package: excl.osi

Arguments: port proto

Get a servent structure by port and protocol. See getservent.

## Appendix A.8 OSI protocols file access

- setprotoent
- endprotoent
- getprotoent
- protoent-p
- protoent-aliases
- protoent-name
- protoent-proto
- getprotobyname
- getprotobynumber

### setprotoent

### Function

#### Package: excl.osi

Arguments: &optional stay-open

This function rewinds the file pointer to the beginning of /etc/protocols so getprotoent can be used to iterate over all the entries. The argument stay-open is non-`nil`, then the file will not be closed between calls to getprotobyname and getprotobynumber.

### endprotoent

### Function

#### Package: excl.osi

Arguments: &rest args

This function closes the protocols file. See getprotoent.

### getprotoent

### Function

#### Package: excl.osi

Arguments:

Return a protoent structure corrsponding to the current entry in the file /etc/protocols. The protoent accessors are used to extract values from the structure, and the functions setprotoent and endprotoent are used to open and close the protocols file.

protoent-p returns true if its argument is a servent structure. The servent accessors are:

- protoent-aliases
- protoent-name
- protoent-proto

The protoent functions are only available on UNIX.

### protoent-p

### Function

#### Package: excl.osi

Arguments: object

Return `t` if the argument is a protoent, `nil` otherwise. See getprotoent.

### protoent-aliases

### Function

#### Package: excl.osi

Arguments: protoent

Accessor for the protoent type. See getprotoent.

### protoent-name

### Function

#### Package: excl.osi

Arguments: protoent

Accessor for the protoent type. See getprotoent.

### protoent-proto

### Function

#### Package: excl.osi

Arguments: protoent

Accessor for the protoent type. See getprotoent.

### getprotobyname

### Function

#### Package: excl.osi

Arguments: name

Get a protoent structure by name. See getprotoent.

### getprotobynumber

### Function

#### Package: excl.osi

Arguments: proto

Get a protoent structure by protocol number. See getprotoent.

## Appendix A.9 OSI process/uid/gid interface functions

- fork
- execve
- pipe
- with-pipe
- wait
- waitpid
- kill
- ctermid
- cuserid
- getlogin
- initgroups
- getgroups
- setgroups
- getpriority
- setpriority
- getpid
- getppid
- getuid
- setuid
- geteuid
- seteuid
- getgid
- setgid
- getegid
- setegid
- setreuid
- setregid
- getpgrp
- setpgrp
- getsid
- setsid
- getpgid
- setpgid
- with-command-output
- command-output
- with-command-io
- get-mem-info

### fork

### Function

#### Package: excl.osi

Arguments:

Create a child process that differs from the parent, the calling process, only in its PID and PPID , and in the fact that resource utiltizations are set to 0. File locks are not inherited.

On success, this function returns twice, once in the parent and once in the child. In the parent, the PID of the child is returned. In the child, 0 is returned. On failure, an error of type `syscall-error` is signaled.

For more information on this UNIX system call, see the fork(2) manual page.

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

### execve

### Function

#### Package: excl.osi

Arguments: filespec argv &optional envp

Execute the program given by filespec with arguments given by the argv and environment given by envp. The currently running program is replaced with the new program, so on success it does not return. On failure an error of type `syscall-error` is signaled.

argv should be a list of strings, and envp a list of strings of the form "name=value". For example:

    (execve "/bin/sh"
            '("sh" "-c" "env")
            '("FOO=bar" "BAZ=bam"))

which might print something like this:

    BAZ=bam
    FOO=bar
    TERM=dumb
    HOSTTYPE=i386
    PATH=/usr/local/bin:/bin:/usr/bin
    SHELL=/bin/csh
    OSTYPE=Linux
    SHLVL=1
    _=/usr/bin/env

If envp is `nil`, then the program is given the null environment.

For more information on this UNIX system call, see the execve(2) manual page.

### pipe

### Function

#### Package: excl.osi

Arguments: &key (mode nil)

Create and returns (as multiple values) a pair of streams, pointing to a pipe. The first returned value is the input stream, used for reading. The second returned value is the output stream, used for writing. On failure an error of type `syscall-error` is signaled.

mode is ignored on all but Windows, where it has a meaning defined by the _pipe() documentation. The constants `_O_TEXT` and `_O_BINARY` are defined by this interface, as `*o-text*` and `*o-binary*`.

Note: on Windows, the blocking behavior of pipes with respect to multiprocessing is currently unknown. Windows has a more common routine for creating pipes, CreatePipe(), but there is no interface to this routine at the current time.

This function was added after the initial release of the OSI interface. Please be sure you have updated with sys:update-allegro after February 10, 2003 to be sure this function is defined in your system.

### with-pipe

### Macro

#### Package: excl.osi

Arguments: (invar outvar) &body body

Binds symbols invar (used for reading from the pipe) and outvar (used for writing to the pipe) to the streams returned by pipe. The macro makes sure the streams are closed when the macro body exits, either normally or in non-local exit situations (i.e., an error or throw). The body is allowed to close either or both streams, without causing an error or warning when the cleanup forms run after the body executes and try to close the streams.

This macro was added after the initial release of the OSI interface. Please be sure you have updated with sys:update-allegro after February 24, 2003 to be sure this function is defined in your system.

### wait

### Function

#### Package: excl.osi

Arguments:

Suspend execution in the current Lisp process until any child process started by the Lisp has exited. The return value is the PID of the child which exited. `(wait)` is equivalent to `(sys:reap-os-subprocess :wait t)`. See reap-os-subprocess.

### waitpid

### Function

#### Package: excl.osi

Arguments: pid &key wnohang wuntraced

Suspend execution in the current Lisp process until the child process given by pid has exited. The wnohang and wuntraced keyword arguments correspond to the WNOHANG and WUNTRACED options of waitpid(2). Currently, wuntraced is unimplemented. waitpid is implemented by this:

    (sys:reap-os-subprocess :pid pid :wait (not wnohang))

See reap-os-subprocess.

### kill

### Function

#### Package: excl.osi

Arguments: pid sig

Send a signal sig to a process pid. On success `t` is returned. On failure an error of type `syscall-error` is signaled. On each UNIX platform and operating system, constants are provided for the various signals. The constant name is the signal name, downcased and surrounded by stars and in the `excl.osi` package: for example `excl.osi:*sigint*` for SIGINT (which is available on all platforms).

See the UNIX manual page for kill(2) for more information on the meaning of the arguments.

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

### ctermid

### Function

#### Package: excl.osi

Arguments:

Return a string which is the pathname for the current controlling terminal for this process. On failure an error of type `syscall-error` is signaled.

See the UNIX manual page for ctermid(3) for more information on this library function.

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

### cuserid

### Function

#### Package: excl.osi

Arguments:

Return a string which is the name of user logged in on the controlling terminal of the process. On failure an error of type `syscall-error` is signaled.

See the UNIX manual page for ctermid(3) for more information on this library function.

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

### getlogin

### Function

#### Package: excl.osi

Arguments:

The same as cuserid.

### initgroups

### Function

#### Package: excl.osi

Arguments: user group

Initialize the group access list by reading the group database /etc/group and using all groups of which user is a member. The additional group group is also added to the list. On success `t` is returned. On failure an error of type `syscall-error` is signaled.

See the UNIX manual page for initgroups(3) for more information on this library function.

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

### getgroups

### Function

#### Package: excl.osi

Arguments: &optional size

This function returns a list of GIDs which correspond to the group access list for the current process. The list will contain no more than size elements. On failure an error of type `syscall-error` is signaled.

See the UNIX manual page for getgroups(2) for more information on this library function.

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

### setgroups

### Function

#### Package: excl.osi

Arguments: groups

Set the group access list for the current process to the list of GIDs in groups. On success `t` is returned. On failure an error of type `syscall-error` is signaled.

See the UNIX manual page for setgroups(2) for more information on this library function.

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

### getpriority

### Function

#### Package: excl.osi

Arguments: which who

Return the scheduling priority of the process, process group or user, as indicated by which and who. On failure an error of type `syscall-error` is signaled. which is one of `*prio-process*`, `*prio-pgrp*`, or `*prio-user*`. who is interpreted relative to which, either a PID, process group identifier or user ID. A zero value for who indicates the current process, process group or user.

See the UNIX manual page for getpriority(2) for more information on this system call.

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

### setpriority

### Function

#### Package: excl.osi

Arguments: which who priority

Set the scheduling priority of the process, process group or user, to priority as indicated by which and who. On failure an error of type `syscall-error` is signaled.

See getpriority for information on which and who. See the UNIX manual page for setpriority(2) for more information on valid values for priority.

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

### getpid

### Function

#### Package: excl.osi

Arguments:

Return the current process ID.

### getppid

### Function

#### Package: excl.osi

Arguments:

Return the parent process ID of the calling process.

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

### getuid

### Function

#### Package: excl.osi

Arguments:

Return the user ID of the current process.

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

### setuid

### Function

#### Package: excl.osi

Arguments: uid

Set the user ID of the current process. On success `t` is returned. 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`.

### geteuid

### Function

#### Package: excl.osi

Arguments:

Return the effective user ID of the current process.

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

### seteuid

### Function

#### Package: excl.osi

Arguments: euid

Set the effective user ID of the current process. On success `t` is returned. 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`.

### getgid

### Function

#### Package: excl.osi

Arguments:

Return the group ID of the current process.

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

### setgid

### Function

#### Package: excl.osi

Arguments: gid

Set the group ID of the current process. On success `t` is returned. 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`.

### getegid

### Function

#### Package: excl.osi

Arguments:

Return the effective group ID of the current process.

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

### setegid

### Function

#### Package: excl.osi

Arguments: egid

Set the effective group ID of the current process. On success `t` is returned. 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`.

### setreuid

### Function

#### Package: excl.osi

Arguments: ruid euid

Set the real and effective user IDs of the current process. On success `t` is returned. 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`.

### setregid

### Function

#### Package: excl.osi

Arguments: rgid egid

Set the real and effective group IDs of the current process. On success `t` is returned. 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`.

### getpgrp

### Function

#### Package: excl.osi

Arguments:

Return the process group ID of the current process.

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

### setpgrp

### Function

#### Package: excl.osi

Arguments:

Set the process group ID of the current process. On success `t` is returned. 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`.

### getsid

### Function

#### Package: excl.osi

Arguments: &optional (pid 0)

Return the session ID of the current process.

This function is not supported on the following platforms, where it signals an error of class `osi-not-supported`:

- MAC OS X (prior to 10.2, it is supported on Mac OS X 10.2)
- Windows

### setsid

### Function

#### Package: excl.osi

Arguments:

Creates a session and sets the process group ID. On success, the new session ID is returned. On failure an error of type `syscall-error` is signaled. See the UNIX manual page for setsid(2) for more information on this system call.

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

### getpgid

### Function

#### Package: excl.osi

Arguments: pgid

Return the process group ID of the specified process.

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

### setpgid

### Function

#### Package: excl.osi

Arguments: pid pgid

Set the process group ID of the specified process. On success `t` is returned. 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`.

### with-command-output

### Macro

#### Package: excl.osi

Arguments: (var command &key directory input error-output (show-window :hide) uid gid effective initgroups-user) &body body

Run program command, binding successive lines of output the program sends to `stdout` to var.

If input is given, it must be a string which is given as input to the program.

If error-output is given, it has the same meaning as the keyword of the same name to run-shell-command, except `:stream` is not an acceptable value. Additionally, it can be a function or symbol naming a function, which is given one argument, a string containing a single line of error output at a time.

show-window is passed directly to run-shell-command directly.

Defined in the lexical context of body are two macros, loop-next and loop-exit. loop-exit causes with-command-output to return. loop-next causes the next line to be read, if there is one.

The return value is the exit status of the program.

### The uid, gid, effective, and initgroups-user keyword arguments

These arguments only have meaning on UNIX platforms. They are not supported on Windows.

uid and gid are numbers representing user and group ids. effective is a boolean which indicates that uid and gid are effective user and group ids. initgroups-user is a string naming a user.

Here is an example using command-output (which also has the new arguments) and then with-command-output:

    cl-user(1): (require :osi)
    ; Fast loading code/osi.fasl
    t
    cl-user(2): (excl.osi:command-output "whoami" :uid 483)
    ("layer")
    nil
    0
    cl-user(3): (excl.osi:command-output "whoami")
    ("root")
    nil
    0
    cl-user(4): (excl.osi:with-command-output (var "whoami" :uid 483)
    	       (format t "output: ~a~%" var))
    output: layer
    0
    cl-user(5):

The gid, initgroups-user, and uid arguments are independent and are processed in the following order, using the indicated system calls (on most UNIX platforms):

gid | setgid(), setegid()
initgroups-user | initgroups()
uid | setuid(), seteuid()

The group is always set first, since after changing users that user may not have permission to change groups.

### A note about error handling

The input, if that option is being used, is given to the program being run in a different Lisp process from the one that evaluated with-command-output. As a result, debugging can be more difficult without emacs, where a *background-interaction* buffer will usually result (if the emacs-lisp interface is running).

This is done so that the process of generating input does not block the process that is reading the output. It is the most efficient, from the lisp point of view.

### command-output

### Function

#### Package: excl.osi

Arguments: command &key directory input (show-window :hide) whole output-file error-output-file uid gid effective initgroups-user

Run command and return three values: a list of stdout lines, stderr lines and exit status.

If directory is given, make that the current working directory before executing command. This is done by changing the directory in a sub-shell started to process command not in the Lisp process that evaluates command-output.

If input is given it can either be a string or a function, both used to generate data for `stdin` of the program. If a function, it must take a single stream argument and output to this stream data for the program. A stream is also a valid value. It should be a stream that will produce input for the executed command.

If output-file or error-output-file are given, they are used as output files for `stdout' and `stderr'. If output-file or error-output-file are given, the corresponding value returned by this function is `nil`.

If whole is non-`nil`, then if there is any output, instead of a list of lines a string containing the entire output is returned, for both `stdout` and `stderr`. If whole is non-`nil` and no output is produced, `nil` (rather than the null string) is returned.

If show-window is given it is used as the show-window keyword argument to run-shell-command. The default is :hide. This keyword is ignored on UNIX.

### The uid, gid, effective, and initgroups-user keyword arguments

These arguments were added in an update made on approximately February 24, 2003. You must have updated with sys:update-allegro subsequent to that date for these arguments to be supported.

These arguments only have meaning on UNIX platforms. They are not supported on Windows.

uid and gid are numbers representing user and group ids. effective is a boolean which indicates that uid and gid are effective user and group ids. initgroups-user is a string naming a user.

Here is an example using command-output (which also has the new arguments):

    cl-user(1): (require :osi)
    ; Fast loading /stuff1/acl/acl70/src/code/osi.fasl
    t
    cl-user(2): (excl.osi:command-output "whoami" :uid 483)
    ("layer")
    nil
    0
    cl-user(3): (excl.osi:command-output "whoami")
    ("root")
    nil
    0
    cl-user(4):

The gid, initgroups-user, and uid arguments are independent and are processed in the following order, using the indicated system calls (on most UNIX platforms):

gid | setgid(), setegid()
initgroups-user | initgroups()
uid | setuid(), seteuid()

The group is always set first, since after changing users that user may not have permission to change groups.

### A note about error handling

The input, if that option is being used, is given to the program being run in a different Lisp process from the one that evaluated command-output. As a result, debugging can be more difficult without emacs, where a *background-interaction* buffer will usually result (if the emacs-lisp interface is running).

This is done so that the process of generating input does not block the process that is reading the output. It is the most efficient, from the lisp point of view.

### What happens when the command does not exist: UNIX and Windows differ

On UNIX platforms, this happens when you try to execute a non-existent command:

    USER(3): (excl.osi:command-output "blarg")
    NIL
    ("blarg: Command not found.")
    1
    User(4):

On Windows, the same form signals an error:

    USER(14): (excl.osi:command-output "blarg")
    Error: "starting shell command" resulted in error
      "No such file or directory"
    [condition type: SYSCALL-ERROR] ...

To avoid an error on Windows, you can preface the command with cmd, like this:

    USER(16): (excl.osi:command-output "cmd /c blarg")
    nil
    ("'blarg' is not recognized as an internal or external command,"
     "operable program or batch file.")
    1
    USER(17):

### with-command-io

### Macro

#### Package: excl.osi

Arguments: (command &key directory (show-window :hide) whole uid gid effective initgroups-user) &rest clauses

Run program command with the input and output coming from forms defined by the clauses. Each clause has the form

    (keyword (var) {forms}*)

where keyword is one of `:input`, `:output` or `:error-output`. All clauses are optional. var is bound by this macro during the evaluation of forms. For `:input`, var is a stream to which output should be sent, that is read by the command as input (stdin). For :output, var is a string representing either a single line of output from the program that was sent to `stdout`, if whole is `nil`, or the entire output of the command, if whole is `t`. `:error-output` is just like `:output`, except it receives data sent to `stderr`.

directory can be used to change the directory in which the program is run. This is given to run-shell-command directly.

On Windows, show-window can be used to change the visibility of the program run. It is ignored on UNIX.

The return value is the exit status of the program.

### The uid, gid, effective, and initgroups-user keyword arguments

These arguments were added in an update made on approximately February 24, 2003. You must have updated with sys:update-allegro subsequent to that date for these arguments to be supported.

These arguments only have meaning on UNIX platforms. They are not supported on Windows.

uid and gid are numbers representing user and group ids. effective is a boolean which indicates that uid and gid are effective user and group ids. initgroups-user is a string naming a user.

Here is an example using command-output (which also has the new arguments):

    cl-user(1): (require :osi)
    ; Fast loading /stuff1/acl/acl70/src/code/osi.fasl
    t
    cl-user(2): (excl.osi:command-output "whoami" :uid 483)
    ("layer")
    nil
    0
    cl-user(3): (excl.osi:command-output "whoami")
    ("root")
    nil
    0
    cl-user(4):

The gid, initgroups-user, and uid arguments are independent and are processed in the following order, using the indicated system calls (on most UNIX platforms):

gid | setgid(), setegid()
initgroups-user | initgroups()
uid | setuid(), seteuid()

The group is always set first, since after changing users that user may not have permission to change groups.

### A note about error handling

The input, if that option is being used, is given to the program being run in a different Lisp process from the one that evaluated with-command-io. As a result, debugging can be more difficult without emacs, where a *background-interaction* buffer will usually result (if the emacs-lisp interface is running).

This is done so that the process of generating input does not block the process that is reading the output. It is the most efficient, from the lisp point of view.

### get-mem-info

### Function

#### Package: excl.osi

Arguments:

Returns two values with information about the Lisp process memory size.

The first value is the resident set size of the Lisp process, in bytes. On Windows, this value corresponds to the Mem Usage column in Task Manager.

The second value represents the virtual memory size of the process (in bytes). This value has a different interpretation between Unix and Windows. On Unix systems, this value represents the amount of virtual address space used by the process. On Windows systems, this value represents the amount of page file space that would be required if the process were fully paged out. It corresponds to the VM size column in Task Manager.

## Appendix A.10 OSI file locking functions

- with-stream-lock
- lockf
- locking
- lock-stream
- unlock-stream

### with-stream-lock

### Macro

#### Package: excl.osi

Arguments: (stream &key (wait t)) &body body

On systems that support file locking, execute body with a lock on stream. lock-stream and unlock-stream are used to lock and unlock stream.

The wait keyword argument is passed to lock-stream. When wait is `nil`, lock-stream will throw an error if the lock cannot be acquired and body will not be executed. If the lock is successfully acquired, then body is evaluated, and the values returned by body are returned.

Note that entire files, not portions of files, are locked and unlocked by lock-stream and unlock-stream.

### lockf

### Function

#### Package: excl.osi

Arguments: stream command length

Apply, test or remove a POSIX lock on an open stream. See the UNIX manual page for lockf(3) for more information on how to use this library function.

This function is not supported on Windows and Mac OS X 10.1, where it signals an error of class `osi-not-supported`. Note: Mac OS X 10.2 and later does have support for lockf.

### locking

### Function

#### Package: excl.osi

Arguments: stream mode length

Apply, test or remove a Windows lock on an open stream. See the Windows API documentation for `_locking` for more information on how to use this library function.

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

### lock-stream

### Function

#### Package: excl.osi

Arguments: stream &key wait

On systems that support file locking, it locks stream for writing, optionally waiting for the lock if the wait keyword argument is specified and non-`nil`. The entire file is locked by this operator, not just a portion of the file. Files are unlocked with unlock-stream.

lock-stream returns `t` if it succeeds. An error is signaled if wait is `nil` and lock-stream fails to acquire a lock.

On Linux (at least) you can only lock a stream that has been opened for input and output (i.e. the open arguments `:direction :io`). On Unix systems lock-stream uses the lockf system call. This is an advisory lock. It does not prevent any process from modifying the file, however processes that also use lockf before accessing a file (such as mail processing programs) will respect your lock on a file.

### unlock-stream

### Function

#### Package: excl.osi

Arguments: stream

On systems that support file locking, it unlocks stream. Files are locked with lock-stream. Note that entire files, not portions of files, are locked and unlocked.

## Appendix A.11 OSI miscellaneous low-level functionality

- sysconf
- `syscall-error`
- syscall-error-errno
- perror
- `osi-not-supported`
- umask
- ttyname
- isatty
- tcgetattr
- tcsetattr
- termios-iflag
- termios-oflag
- termios-cflag
- termios-lflag
- disable-terminal-echo
- enable-terminal-echo
- with-terminal-echo-disabled
- chroot
- strerror
- strsignal
- crypt
- gethostname
- gethostbyname
- gethostbyaddr
- getdomainname
- ntohl
- ntohs
- htonl
- htons
- detach-from-terminal-supported-p
- detach-from-terminal
- acct
- openlog
- closelog
- syslog
- getenv
- setenv
- unsetenv
- putenv
- environment
- sync

### sysconf

### Function

#### Package: excl.osi

Arguments: name

Get configuration information at runtime, giving by the integer name. name is one of the `_SC_*` constants defined by POSIX, which are exported by the excl.osi package (see Lisp constants corresponding to Operating System constants).

This function is not supported on Windows, where it signals an error.

Example (on Linux):

    cl-user(6): (sysconf *sc-open-max*)
    1024
    cl-user(7):

Which is the same as calling `sysconf(_SC_OPEN_MAX)` in C.

### syscall-error

### Class

#### Package: excl.osi

A condition type that inherits behavior from condition class `error`. `syscall-error` adds a slot `errno`, which holds the value of the system error generated with conditions of this type. The accessor syscall-error-errno can be used to retrieve this value from instances of this class.

### syscall-error-errno

### Function

#### Package: excl.osi

Arguments: syscall-error

An accessor for instances of `syscall-error`.

### perror

### Function

#### Package: excl.osi

Arguments: errno format-string &rest format-args

Signal an error of type `syscall-error`, using errno to construct an appropriate error message.

### osi-not-supported

### Class

#### Package: excl.osi

A condition class used for errors of unsupported functionality.

### umask

### Function

#### Package: excl.osi

Arguments: mode

Set the file creation mask to mode and return the previous mask. The file creation mask must be an integer bewteen 0 and 17141 (7777 in octal). The file creation mask specifies the permissions for various classes of users. It is described in https://en.wikipedia.org/wiki/Umask.

### ttyname

### Function

#### Package: excl.osi

Arguments: stream

Return a string naming the terminal device that is open on stream.

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

### isatty

### Function

#### Package: excl.osi

Arguments: stream

Return `t` if stream is an open stream connected to a terminal and `nil` otherwise.

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

### tcgetattr

### Function

#### Package: excl.osi

Arguments: stream

If successful, returns a "termios" object that represents the current state of the terminal associated with stream. If unsuccessful, an error will be generated. See the system man page for tcgetattr(3) for details.

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

### tcsetattr

### Function

#### Package: excl.osi

Arguments: stream termios &key action

This function updates the terminal state associated with stream. 'termios' should be an object that was previously returned by tcgetattr for the same stream. action (which defaults to `*tcsanow*`) specifies when the changes should take effect. Possible values for action are `*tcsanow*`, `*tcsadrain*` and `*tcsaflush*`.

If successful, the function returns `t`, otherwise an error is generated. See the system man page for tcsetattr(3) for details.

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

### termios-iflag

### Function

#### Package: excl.osi

Arguments: termios

This function retrieves the value of the iflag slot of the termios object. See the system man page for tcgetattr(3) for details.

termios objects are returned by tcgetattr.

This function is setfable.

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

### termios-oflag

### Function

#### Package: excl.osi

Arguments: termios

This function retrieves the value of the oflag slot of the termios object. See the system man page for tcgetattr(3) for details.

termios objects are returned by tcgetattr.

This function is setfable.

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

### termios-cflag

### Function

#### Package: excl.osi

Arguments: termios

This function retrieves the value of the cflag slot of the termios object. See the system man page for tcgetattr(3) for details.

termios objects are returned by tcgetattr.

This function is setfable.

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

### termios-lflag

### Function

#### Package: excl.osi

Arguments: termios

This function retrieves the value of the lflag slot of the termios object. See the system man page for tcgetattr(3) for details.

termios objects are returned by tcgetattr.

This function is setfable.

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

### disable-terminal-echo

### Function

#### Package: excl.osi

Arguments: stream &key echo-newline

This function disables terminal echo on stream. If echo-newline is true, then newline characters will still be echoed anyway. See the documentation for with-terminal-echo-disabled for an example.

Keep in mind that if you are running Lisp within Emacs, character echo may occur even when you've called this function, because Emacs does its own echoing.

If successful, the function returns `t`, otherwise an error is generated.

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

### enable-terminal-echo

### Function

#### Package: excl.osi

Arguments: stream

This function enables terminal echo on stream.

If successful, the function returns `t`, otherwise an error is generated.

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

### with-terminal-echo-disabled

### Macro

#### Package: excl.osi

Arguments: (stream &key echo-newline) &body body

This macro disables terminal echo on stream, evaluates body, and then restores the prior terminal state. The terminal state is restored even if body finishes abnormally.

If echo-newline is true, newline characters will still be echoed. See below for an example of how that is sometimes useful.

Errors are ignored when attempting to disable/enable character echo. (Therefore, this macro works on Windows, although it has no effect on character echo).

The following example shows the use of with-terminal-echo-disabled with echo-newline nil and non-nil. In both cases, when the program prompted for the secret word, a word was typed, followed by the enter/return key. The word that was typed is not visible in the transcript due to terminal echo being successfully disabled. In the first call, "Thank You" appears on the same line as the prompt, because the user's enter/return keystroke was not echoed. In the second call, "Thank You" appears on a new line because the user's enter/return keystroke was echoed.

    cl-user(2): (defun test-echo (arg)
                  (excl.osi:with-terminal-echo-disabled (*terminal-io*
                                             :echo-newline arg)
                  (format t "Please type the secret word: ")
                  (read-line)
                  (format t "Thank you.~%")
                  t))
    test-echo
    cl-user(3): (test-echo nil)
    Please type the secret word: Thank you.
    t
    cl-user(4): (test-echo t)
    Please type the secret word:
    Thank you.
    t

### chroot

### Function

#### Package: excl.osi

Arguments: filespec

Changes the root directory to that specified by filespec. On success `t` is returned. 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`.

### strerror

### Function

#### Package: excl.osi

Arguments: errno

Returns a string describing the error code passed in errno, or an unknown error message if the error code is unknown.

### strsignal

### Function

#### Package: excl.osi

Arguments: signo

This function returns a string describing the signal code passed in signo, or `nil` if the signal code is unknown. On UNIX machines, it acts like the UNIX library function strsignal() and also works on Windows (where strsignal() is not defined but the information is otherwise available).

### crypt

### Function

#### Package: excl.osi

Arguments: string salt

Return a string which is the DES encryption of string and salt. See the UNIX manual page crypt(3) for more information. 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`. On UNIX, the library routine is expected to be in libcrypt or a system library already loaded into ACL. If it is not, an error is signaled which suggests how to remedy the situation.

The value of the variable excl.osi:*libcrypt* is the name of the crypt library used by the crypt function. This symbol was added by a patch released in late March, 2006.

### gethostname

### Function

#### Package: excl.osi

Arguments: &optional size

Return at most size bytes of the hostname of the current processor. The default for size is 128. 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`.

### gethostbyname

### Function

#### Package: excl.osi

Arguments: host &key raw values ignore-cache

Return a string containing the IP address of host. If the raw keyword is non-`nil`, then a 32-bit is returned instead of a string. If the values keyword is non-`nil` and raw is `nil`, then each of the parts of the IP address are returned as values, the first being the most significant byte (`a' from `a.b.c.d'). If the ignore-cache keyword is non-`nil`, then no cached values are used.

If host cannot be found, an error is signaled.

See also gethostbyaddr.

Using gethostbyname can cause the Lisp to freeze for the duration of the call (which can be up to a minute if it takes a long time to get a response from a DNS server). We recommend using lookup-hostname instead. It uses, by default, Allegro CL's own DNS client routines to look up the information.

### gethostbyaddr

### Function

#### Package: excl.osi

Arguments: addr &key ignore-cache

Return the host name for a given IP address. This is the reverse of what gethostbyname does. If no host name can be found, `nil` is returned.

Using gethostbyaddr can cause the Lisp to freeze for the duration of the call (which can be up to a minute if it takes a long time to get a response from a DNS server). We recommend using ipaddr-to-hostname instead. It uses, by default, Allegro CL's own DNS client routines to look up the information.

### getdomainname

### Function

#### Package: excl.osi

Arguments: &optional size

Return at most size bytes of the domain name of the current processor. The default for size is 128. 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`.

### ntohl

### Function

#### Package: excl.osi

Arguments: val

Convert the long integer val from network byte order to host byte order.

### ntohs

### Function

#### Package: excl.osi

Arguments: val

Convert the short integer val from network byte order to host byte order.

### htonl

### Function

#### Package: excl.osi

Arguments: val

Convert the long integer val from host byte order to network byte order.

### htons

### Function

#### Package: excl.osi

Arguments: val

Convert the short integer val from host byte order to network byte order.

### detach-from-terminal-supported-p

### Function

#### Package: excl.osi

Arguments:

Return `t` if detach-from-terminal is supported on this version of ACL, `nil` otherwise.

### detach-from-terminal

### Function

#### Package: excl.osi

Arguments: &key output-stream error-output-stream

Detach the current process from the terminal associated with that process. This is for daemonizing a process. The keywords output-stream and error-output-stream are used for setting up what the UNIX notions of `stdout' and `stderr' are set to. The value nil (the default) for output-stream and error-output-stream, the stream associated with /dev/null is used.

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

### acct

### Function

#### Package: excl.osi

Arguments: filespec

If filespec is non-`nil`, then turn process accounting on, otherwise turn it off. On success `t` is returned. On failure an error of type `syscall-error` is signaled.

The file created by acct is in a system dependent format.

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

### openlog

### Function

#### Package: excl.osi

Arguments: ident option facility

Open a connection to the system logger.

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

The following are constants that can be passed to openlog: `*log-alert*`, `*log-auth*`, `*log-authpriv*`, `*log-cons*`, `*log-cron*`, `*log-daemon*`, `*log-debug*`, `*log-emerg*`, `*log-err*`, `*log-ftp*`, `*log-info*`, `*log-kern*`, `*log-local0*`, `*log-local1*`, `*log-local2*`, `*log-local3*`, `*log-local4*`, `*log-local5*`, `*log-local6*`, `*log-local7*`, `*log-lpr*`, `*log-mail*`, `*log-ndelay*`, `*log-news*`, `*log-notice*`, `*log-perror*`, `*log-pid*`, `*log-syslog*`, `*log-user*`, `*log-uucp*`, `*log-warning*`.

### closelog

### Function

#### Package: excl.osi

Arguments:

Close the connection to the system logger.

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

### syslog

### Function

#### Package: excl.osi

Arguments: priority format-string &rest format-arguments

Generate a log message handled by the system logger. See the UNIX manual page for syslog(3) for more information.

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

The following are constants that can be passed to syslog: `*log-alert*`, `*log-debug*`, `*log-emerg*`, `*log-err*`, `*log-info*`, `*log-notice*`, `*log-warning*`.

### getenv

### Function

#### Package: system

Arguments: string

Return the value of the environment variable given by string, or `nil` if it is not defined.

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. Its manual page is here.

See Section 6.0 Polling and setting environment variables.

### setenv

### Function

#### Package: excl.osi

Arguments: name value overwrite

Add name to the environment, with value value, if it does not already exist. If it does exist, change the value to value if overwrite is non-`nil`, leave it alone if overwrite is `nil`. On success `t` is returned (leaving an existing value alone when overwrite is `nil` is a successful outcome). On failure an error of type `syscall-error` is signaled.

This function is not supported on the following platforms, where it signals an error of class `osi-not-supported`:

- HP-UX (all varieties)
- Solaris
- Windows

See Section 6.0 Polling and setting environment variables.

### unsetenv

### Function

#### Package: excl.osi

Arguments: name

Remove environment variable name from the environment. Always returns `t`.

This function is not supported on the following platforms, where it signals an error of class `osi-not-supported`:

- AIX (on IBM machines)
- HP-UX (all varieties)
- Solaris
- Windows

See Section 6.0 Polling and setting environment variables.

### putenv

### Function

#### Package: excl.osi

Arguments: string

Add environment information as specifed by string, which has the form "name=value", adding or setting a variable name to value value.

    (putenv "name=value")

is equivalent to

    (setenv "name" "Value" t)

See setenv.

`t` is returned if the operation succeeds. If it fails, an error of type `syscall-error` is signaled.

See Section 6.0 Polling and setting environment variables.

### environment

### Function

#### Package: excl.osi

Arguments:

Return a list of the original environment when Lisp was started, each element of which has the form of (var . value). Any changes to the environment with setenv, putenv or setf of getenv are not reflected in the value returned by this function.

### sync

### Function

#### Package: excl.osi

Arguments:

Flush filesystem buffers to disk. See the sync(2) UNIX man page for details.

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

## Appendix A.12 OSI miscellaneous higher-level functionality

- same-file-p
- same-filesystem-p
- find-in-path
- compare-files

### same-file-p

### Function

#### Package: excl.osi

Arguments: filespec1 filespec2

Return `t` if the files given by filespec1 and filespec2 are the same file, and `nil` otherwise.

### same-filesystem-p

### Function

#### Package: excl.osi

Arguments: filespec1 filespec2

Return `t` if the files filespec1 and filespec2 reside on the same filesystem, and `nil` otherwise.

### find-in-path

### Function

#### Package: excl.osi

Arguments: name &key executable

Return a pathname of the absolute pathname found when searching for name in the directories given by the value of the environment variable `PATH`. The executable keyword argument is ignored on Windows. On UNIX platforms, if executable is specified true, it causes only matches of files that have execute bit set in their mode to be returned.

### compare-files

### Function

#### Package: excl.osi

Arguments: filespec1 filespec2

Compare the contents of filespec1 and filespec2, returning `t` if they are the same, `nil` otherwise.

## Appendix A.13 Lisp constants corresponding to Operating System constants

The `:excl.osi` package includes symbols naming Lisp constants which correspond to operating system constants. We have documented all the constants in a separate file (to make the size of this file more manageable). See osi-constants.htm. Note that Not every constant is defined on every platform (architecture).

osi-constants.htm has two sections:

1. Lisp constants corresponding to Operating System constants. In this section rules for converting an operating system constant name to a list constant name (if there is one) are given.
2. Defined Operating System/Lisp constants by architecture. This section lists each supported architecture and the constants defined in that architecture.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 8.2 page.
Created 2019.8.20.

ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Moderately revised from 8.2. 8.2 version