|
Allegro CL version 11.0 | ||||||||
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.
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): 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. |
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 |
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). |
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] 8You 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.
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.
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.
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): 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. |
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 |
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). |
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] 8You 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.
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.
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.)
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.
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.
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.)
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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
function, package: excl.osi
Arguments: f
Accessor for the value returned by stat.
function, package: excl.osi
Arguments: f
Accessor for the value returned by stat.
function, package: excl.osi
Arguments: f
Accessor for the value returned by stat.
function, package: excl.osi
Arguments: f
Accessor for the value returned by stat.
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.
function, package: excl.osi
Arguments: f
Accessor for the value returned by stat.
function, package: excl.osi
Arguments: f
Accessor for the value returned by stat.
function, package: excl.osi
Arguments: f
Accessor for the value returned by stat.
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.
function, package: excl.osi
Arguments: f
Accessor for the value returned by stat.
function, package: excl.osi
Arguments: stream
This function is just like the function stat except that it operates on an open stream.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
function, package: excl.osi
Arguments: dir
Close the directory handle associated with dir. On failure signal an error of type syscall-error.
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.
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.
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.
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.
;; 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): function, package: excl.osi
Arguments: template &key (external-format :default) (class 'file-simple-stream)
This function returns two values:
An open input/output stream
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.
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.
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))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.
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.
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*.
function, package: excl.osi
Arguments:
Return the current working directory as a pathname. This function is the same as current-directory.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
function, package: excl.osi
Arguments: &rest args
This function closes the /etc/passwd file. See 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.
function, package: excl.osi
Arguments: name
Get a pwent structure by name. See getpwent.
function, package: excl.osi
Arguments: uid
Get a pwent structure by uid. See getpwent.
function, package: excl.osi
Arguments: object
Return t if the argument is a pwent, nil otherwise. See getpwent.
function, package: excl.osi
Arguments: struct
Accessor for the pwent type. See getpwent.
function, package: excl.osi
Arguments: struct
Accessor for the pwent type. See getpwent.
function, package: excl.osi
Arguments: struct
Accessor for the pwent type. See getpwent.
function, package: excl.osi
Arguments: pwent
Accessor for the pwent type. See getpwent.
function, package: excl.osi
Arguments: pwent
Accessor for the pwent type. See getpwent.
function, package: excl.osi
Arguments: pwent
Accessor for the pwent type. See getpwent.
function, package: excl.osi
Arguments: pwent
Accessor for the pwent type. See getpwent.
function, package: excl.osi
Arguments:
Return t if shadow passwd support is available on this version of Lisp.
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.
function, package: excl.osi
Arguments: &rest args
This function closes the shadow passwd file. See getspent and setspent.
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.
function, package: excl.osi
Arguments: name
Get a spwd structure by name. See getspent.
function, package: excl.osi
Arguments: object
Return t if the argument is a spwd, nil otherwise. See getspent.
function, package: excl.osi
Arguments: spwd
Accessor for the spwd type. See getspent.
function, package: excl.osi
Arguments: spwd
Accessor for the spwd type. See getspent.
function, package: excl.osi
Arguments: spwd
Accessor for the spwd type. See getspent.
function, package: excl.osi
Arguments: spwd
Accessor for the spwd type. See getspent.
function, package: excl.osi
Arguments: spwd
Accessor for the spwd type. See getspent.
function, package: excl.osi
Arguments: spwd
Accessor for the spwd type. See getspent.
function, package: excl.osi
Arguments: spwd
Accessor for the spwd type. See getspent.
function, package: excl.osi
Arguments: spwd
Accessor for the spwd type. See getspent.
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.
function, package: excl.osi
Arguments: &rest args
This function closes the group file. See 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.
function, package: excl.osi
Arguments: object
Return t if the argument is a grent, nil otherwise. See getgrent.
function, package: excl.osi
Arguments: gid
Accessor for the grent type. See getgrent.
function, package: excl.osi
Arguments: gid
Accessor for the grent type. See getgrent.
function, package: excl.osi
Arguments: gid
Accessor for the grent type. See getgrent.
function, package: excl.osi
Arguments: gid
Accessor for the grent type. See getgrent.
function, package: excl.osi
Arguments: name
Get a grent structure by name. See getgrent.
function, package: excl.osi
Arguments: gid
Get a grent structure by uid. See getgrent.
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.
function, package: excl.osi
Arguments: &rest args
This function closes the networks file. See 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.
function, package: excl.osi
Arguments: object
Return t if the argument is a netent, nil otherwise. See getnetent.
function, package: excl.osi
Arguments: netent
Accessor for the netent type. See getnetent.
function, package: excl.osi
Arguments: netent
Accessor for the netent type. See getnetent.
function, package: excl.osi
Arguments: netent
Accessor for the netent type. See getnetent.
function, package: excl.osi
Arguments: netent
Accessor for the netent type. See getnetent.
function, package: excl.osi
Arguments: name
Get a netent structure by name. See getnetent.
function, package: excl.osi
Arguments: net type
Get a netent structure by address and type. See getnetent.
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.
function, package: excl.osi
Arguments: &rest args
This function closes the services file. See 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.
function, package: excl.osi
Arguments: object
Return t if the argument is a servent, nil otherwise. See getservent.
function, package: excl.osi
Arguments: servent
Accessor for the servent type. See getservent.
function, package: excl.osi
Arguments: servent
Accessor for the servent type. See getservent.
function, package: excl.osi
Arguments: servent
Accessor for the servent type. See getservent.
function, package: excl.osi
Arguments: servent
Accessor for the servent type. See getservent.
function, package: excl.osi
Arguments: name proto
Get a servent structure by name and protocol. See getservent.
function, package: excl.osi
Arguments: port proto
Get a servent structure by port and protocol. See getservent.
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.
function, package: excl.osi
Arguments: &rest args
This function closes the protocols file. See 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.
function, package: excl.osi
Arguments: object
Return t if the argument is a protoent, nil otherwise. See getprotoent.
function, package: excl.osi
Arguments: protoent
Accessor for the protoent type. See getprotoent.
function, package: excl.osi
Arguments: protoent
Accessor for the protoent type. See getprotoent.
function, package: excl.osi
Arguments: protoent
Accessor for the protoent type. See getprotoent.
function, package: excl.osi
Arguments: name
Get a protoent structure by name. See getprotoent.
function, package: excl.osi
Arguments: proto
Get a protoent structure by protocol number. See getprotoent.
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.
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/envIf 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.
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.
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.
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.
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.
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.
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.
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.
function, package: excl.osi
Arguments:
The same as cuserid.
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.
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.
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.
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.
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.
function, package: excl.osi
Arguments:
Return the current process ID.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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): 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
function, package: excl.osi
Arguments: syscall-error
An accessor for instances of syscall-error.
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.
Class, package: excl.osi
A condition class used for errors of unsupported functionality.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
tfunction, 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.
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.
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).
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.
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.
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.
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.
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.
function, package: excl.osi
Arguments: val
Convert the long integer val from network byte order to host byte order.
function, package: excl.osi
Arguments: val
Convert the short integer val from network byte order to host byte order.
function, package: excl.osi
Arguments: val
Convert the long integer val from host byte order to network byte order.
function, package: excl.osi
Arguments: val
Convert the short integer val from host byte order to network byte order.
function, package: excl.osi
Arguments:
Return t if detach-from-terminal is supported on this version of ACL, nil otherwise.
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.
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.
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*.
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.
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*.
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.
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.
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.
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.
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.
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.
function, package: excl.osi
Arguments: filespec1 filespec2
Return t if the files given by filespec1 and filespec2 are the same file, and nil otherwise.
function, package: excl.osi
Arguments: filespec1 filespec2
Return t if the files filespec1 and filespec2 reside on the same filesystem, and nil otherwise.
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.
function, package: excl.osi
Arguments: filespec1 filespec2
Compare the contents of filespec1 and filespec2, returning t if they are the same, nil otherwise.
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:
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.
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.
|
Allegro CL version 11.0 | ||||||||