ToC DocOverview CGDoc RelNotes FAQ Index PermutedIndex
Allegro CL version 11.0

Operating System Interface


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 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 Operating System Interface Functionality.


2.0 Subprocess functions

The new OSI interface (see 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 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-commandwho execute a simple command ().

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 The Operating System Interface (OSI) module) includes many operators related to the file system, similar to the operators described in this section. See 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 The Operating System Interface (OSI) module). See 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 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/acl110/.

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/acl110/"
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 OSI file handling functionality for descriptions of the new functionality.

Function Arguments Notes
copy-directory from-dir to-dir &key quiet &allow-other-keys Copies from-dir to to-dir. Accepts copy-file keywords for copying files in the directory being copied.
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. See also the other functions in the new :osi module associated with filesystem manipulation, described in OSI file handling functionality.
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 OSI file handling functionality.
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 OSI file handling functionality.
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.
file-directory-p filespec Returns true if argument names a directory.
make-directory pathname &optional mode Creates a directory named by pathname.
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 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 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
temporary-directory Returns the pathname of the temporary directory used by the current running Lisp for writing temporary files.
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 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 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 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.html 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
command-line-argument (n &key application) Returns the value of the nth command-line arguments.
command-line-arguments (&key application) Returns a list of all command-line arguments.
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.html 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 The Operating System Interface (OSI) module) includes more operators for setting, changing, and unsetting environment variables. These are described OSI miscellaneous low-level functionality.

The function system: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). system: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 system: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 system: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 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.html for details.

See Operating System Interface Functionality.


8.0 Subprocess functions

The new OSI interface (see 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 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-commandwho 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): 

9.0 Filesystem manipulation functions

The new OSI interface (see The Operating System Interface (OSI) module) includes many operators related to the file system, similar to the operators described in this section. See 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 The Operating System Interface (OSI) module). See 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 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/acl110/.

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/acl110/"
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 OSI file handling functionality for descriptions of the new functionality.

Function Arguments Notes
copy-directory from-dir to-dir &key quiet &allow-other-keys Copies from-dir to to-dir. Accepts copy-file keywords for copying files in the directory being copied.
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. See also the other functions in the new :osi module associated with filesystem manipulation, described in OSI file handling functionality.
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 OSI file handling functionality.
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 OSI file handling functionality.
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.
file-directory-p filespec Returns true if argument names a directory.
make-directory pathname &optional mode Creates a directory named by pathname.
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.

10.0 Temporary directory and files

The OSI interface (see 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 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
temporary-directory Returns the pathname of the temporary directory used by the current running Lisp for writing temporary files.
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 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 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 The Operating System Interface (OSI) module).

11.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.html 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
command-line-argument (n &key application) Returns the value of the nth command-line arguments.
command-line-arguments (&key application) Returns a list of all command-line arguments.
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.html 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.


12.0 Polling and setting environment variables

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

The function system: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). system: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 system: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 system: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.


13.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 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.html for details.

See 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.)


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


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

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

Classes

Constants

We have provided Lisp constants corresponding to the various operating system constants. The Lisp constants typically provide default values for various arguments. See Lisp constants corresponding to Operating System constants and the separate document osi-constants.html 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.html, 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.)


14.1 OSI file handling functionality


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

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 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 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 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 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. Calling it on that 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 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) (class 'file-simple-stream)

This function returns two values:

  1. An open input/output stream

  2. The selected temporary filename, which is created from template

template must end with six X's which will be replaced with characters that form a unique filename. The external-format keyword can be used to specify the external-format used to open the stream. The class keyword can be used to specify the class of stream that is created. See cl:open implmentation in implementation.html for detals.

mkstemp, like the UNIX counterpart, is free of race conditions on opening the file. On failure an error of type syscall-error is signaled.

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

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 Temporary directory and files.


with-open-temp-file

macro, package: excl.osi

Arguments: (var template &key filename delete external-format (class 'file-simple-stream) &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 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 value of the class argument is passed as the class keyword argument to mkstemp. See the description of that function for information on suitable values for class (where you will be referred to cl:open implementation in implementation.html).

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

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: excl.osi

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 with-open-file analog using os-open instead of 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 with-open-file except it uses os-open instead of 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.


os-close

function, package: excl.osi

Arguments: stream

The same as 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.

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.


14.2 OSI time functionality


universal-to-unix-time

function, package: excl.osi

Arguments: universal-time

Convert the argument universal-time to a UNIX time. See 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 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 System calls and library routines dealing with time for more information.


14.3 OSI password functionality


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:

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.


14.4 OSI shadow password functionality


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:

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.


14.5 OSI group file access


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:

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.


14.6 OSI networks file access


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:

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.


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.


14.7 OSI services file access


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:

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.


14.8 OSI protocols file access


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:

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.


14.9 OSI process/uid/gid interface functions


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 #+mswindows *o-binary* #-mswindows 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.


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.


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:


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


14.10 OSI file locking functions


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.


14.11 OSI miscellaneous low-level functionality


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 is actually an alias for nice-signal-name. Like that function, it 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: excl.osi

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 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 Windows, where it signals an error of class osi-not-supported:

See 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 Windows, where it signals an error of class osi-not-supported.

See 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 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 system: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.


14.12 OSI miscellaneous higher-level functionality


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.


14.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.html. Note that Not every constant is defined on every platform (architecture).

osi-constants.html 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) Franz Inc. Lafayette, CA., USA. All rights reserved.

ToC DocOverview CGDoc RelNotes FAQ Index PermutedIndex
Allegro CL version 11.0