| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version | ||||||||
This document contains the following sections:
1.0 Operating-system interfaceThis chapter describes some functions in Allegro CL that interact with the host operating system. These functions include those providing access and control of system services, which, on UNIX and Linux, are typically found in chapters 2 and 3 of the UNIX manual.
A :osi module is described in
Section 7.0 The Operating System Interface (OSI) module below. Functionality
described in all sections of this document is enhanced, so every
section is changed in some fashion. The operators, constants, and
classes of the new module are not described (in this documentation
release) on individual documentation pages. Instead, the descriptions
are in Appendix A Operating System Interface Functionality.
The new OSI interface (see Section 7.0 The Operating System Interface (OSI) module) includes the function command-output and the macros with-command-output and with-command-io. Those operators also execute operating system commands and can be used along with or in place of the functions described in this section. They are higher-level than run-shell-command and shell and are now recommended when the interaction with the subprocess requires input or produces output that must be captured. The new operators do not have separate description pages. They are described in Appendix A.9 OSI process/uid/gid interface functions.
Allegro CL has the ability to run UNIX and Windows child processes controlled from Lisp. Starting a subprocess and communicating with it are slower than using the foreign function interface to accomplish the same task, but it is sometimes unavoidable. Creating very many simultaneous subprocesses may be limited by system resources.
Subprocesses can be started with run-shell-command and shell, and with the newly-added operators command-output, with-command-output, and with-command-io.
If run-shell-command is
called with the wait keyword argument nil, reap-os-subprocess (or os-wait) must be called to clear the process
from the system. Failure to do this will eventually cause the system
to be unable to create new processes. Further, the streams opened by
run-shell-command must be
closed by the program. The system will not close them
automatically. In contrast, the newly-added operators command-output, with-command-output, and with-command-io handle reaping
the processes and closing the stream themselves.
Here are a couple of examples, both on Unix, of run-shell-command followed by examples using the new functionality. (There are more examples of using run-shell-command on its description page).
In the first, we simply have run-shell-command execute a simple command (who).
USER(1): (run-shell-command "who") sdj ttyp0 Aug 18 16:08 (rubix) adam ttyp2 Aug 18 16:17 (rubix) dm ttyp4 Aug 19 10:24 (rubix) 0 USER(2):
The second example is more complicated. We cause run-shell-command to spawn a shell and then we communicate with the shell via the stream set up by run-shell-command.
;; First we define a function to read the output from the shell. This
;; function is pretty simple -- it reads characters and prints them
;; out but it does show how a more useful function could be implemented.
USER(24): (defun get-from-shell (stream)
(do ((ch (read-char-no-hang stream)
(read-char-no-hang stream)))
((null ch))
(write-char ch)))
GET-FROM-SHELL
;; Now we initiate the shell:
USER(25): (setq shell-stream (excl:run-shell-command "csh"
:input :stream
:output :stream
:wait nil))
#<EXCL::BIDIRECTIONAL-TERMINAL-STREAM @ #x10a4aa6>
USER(26): (format shell-stream "who~%")
NIL
USER(27): (force-output shell-stream)
NIL
USER(28): (get-from-shell shell-stream)
rlogin ttya Aug 19 07:06
rlogin ttyb Aug 19 08:26
sdj ttyp0 Aug 18 16:08 (rubix)
cheetham ttyp1 Aug 18 17:17 (frozen)
adam ttyp2 Aug 18 16:17 (rubix)
NIL
;; We exit the shell:
USER(29): (format shell-stream "exit~%")
NIL
;; and close the stream.
USER(30): (close shell-stream)
T
;; We call sys:reap-os-subprocess because we called
;; run-shell-command with :wait nil:
USER(31): (sys:reap-os-subprocess)
0
27201
USER(32):
Here are some examples using the new operators command-output, with-command-output, and with-command-io.
cl-user(1): (require :osi)
;; fast-loading osi.fasl
t
cl-user(2): (use-package :excl.osi)
t
cl-user(3): (command-output "who")
("mikel pts/0 Oct 3 15:38 (ultra)"
"layer pts/1 Oct 22 10:26 (crikey)")
nil
0
cl-user(4): (command-output "who" :whole t)
"mikel pts/0 Oct 3 15:38 (ultra)
layer pts/1 Oct 22 10:26 (crikey)
"
nil
0
cl-user(5): (command-output "cat" :input "this is multi-line
input for the cat program")
("this is multi-line" "input for the cat program")
nil
0
cl-user(6): (with-command-io ("cat")
(:input (stream)
(format stream "cat this~%")
(format stream "cat this, too~%"))
(:output (line)
(format t "output: ~a~%" line)))
output: cat this
output: cat this, too
0
cl-user(7): (with-command-output (line "cat /etc/issue")
(format t "output: ~a~%" line))
output:
output: Red Hat Linux release 6.0 (Hedwig)
output: Kernel 2.2.19 on an i686
output:
0
cl-user(8):
The new OSI interface (see Section 7.0 The Operating System Interface (OSI) module) includes many operators related to the file system, similar to the operators described in this section. See Appendix A.1 OSI file handling functionality for descriptions of all the new functionality relevant to this section.
The following functions provide information about directories in the system:
| Name | Arguments | Notes |
| chdir | &optional pathname | Make pathname the current directory. If unspecified, make the current user's home directory the current directory (UNIX) or make c:\ the current directory (Windows). See the full description as the function has some oddities. See also the example below. |
| current-directory | Returns the current directory. | |
| getcwd | Another name for current-directory. Added with the new OSI interface (see Section 7.0 The Operating System Interface (OSI) module). See Appendix A.1 OSI file handling functionality for descriptions of all the new functionality relevant to this section. Returns the current directory. | |
| username-to-home-directory | name | On Unix, returns the home directory
of the user named by the
argument. On Windows, uses the value of the HOME
environment variable; uses C:\\ if that variable
is not set. |
Examples using excl:chdir. The current users home directory is /usr/tech/doe/. The directory /usr/tech/doe/tmp/ exists. The Allegro directory for the Lisp is (in this example) /usr/acl70/.
user(15): (chdir) ;; no argument: change to user home directory
"/usr/tech/doe/"
user(16): (chdir "sys:") ;; a string naming a logical pathname
;; which translates
;; to the Lisp home directory.
"/usr/acl70/"
user(17): (chdir)
"/usr/tech/doe/"
user(18): (chdir "tmp") ;; change to the tmp/ subdirectory
"tmp/"
user(19): (chdir (make-pathname :directory "tmp"))
;; The absolute directory
;; /tmp/
"/tmp/"
user(20): (chdir)
"/usr/tech/doe/"
user(21):
The following functions provide information about or manipulate files and/or directories:
The :osi module has many
new functions associated with filesystem manipulation. See
Appendix A.1 OSI file handling functionality for descriptions of
the new functionality.
| Function | Arguments | Notes |
| excl:copy-directory | from-dir to-dir &key quiet &allow-other-keys | Copies from-dir to to-dir. Accepts sys:copy-file keywords for copying files in the directory being copied. |
| sys:copy-file | from-pathname to-pathname &key link preserve-symbolic-links element-type preserve-time remove-destination force | Copies from-pathname to to-pathname
preserving features as specified by keyword arguments.
Note: link argument was called link-ok
in releases 5.0.1 and earlier. See also the other functions in the
new :osi module associated with filesystem
manipulation, described in
Appendix A.1 OSI file handling functionality. |
| excl:delete-directory | pathname | Deletes the directory named by pathname, which must
be an empty directory. See also the new function
rmdir and other functions in the
new :osi module associated with filesystem
manipulation, described in
Appendix A.1 OSI file handling functionality. |
| excl:delete-directory-and-files | directory &key if-does-not-exist quiet force | Deletes the directory named by
directory and all of
its subdirectories and files. See also the new functions in the
new :osi module associated with filesystem
manipulation, described in
Appendix A.1 OSI file handling functionality. |
| excl:directory-size | dirname &key roundup | Returns the size in bytes of
all the files in the directory named by dirname and all
its subdirectories. If
roundup is non-nil,
its value must be an integer, and the result will be
rounded up to a multiple of that integer. |
| excl:file-directory-p | filespec | Returns true if argument names a directory. |
| excl:make-directory | pathname &optional mode | Creates a directory named by pathname. |
| excl:map-over-directory | function directory &key filter prune-directories include-directories file-type recurse | Applies function to the entries in directory, with keywords allowing for finer control. |
The OSI interface (see Section 7.0 The Operating System Interface (OSI) module) includes operators like mkstemp, mkdtemp, and with-open-temp-file. These operators provide functionality related to the operators described in this section. See Appendix A.1 OSI file handling functionality.
Allegro CL may need to write temporary files while it runs. The first function following returns the directory used by the current running Lisp as its temporary directory. The second returns an unused filename in that directory.
| Name | Arguments | Notes |
| system:temporary-directory | Returns the pathname of the temporary directory used by the current running Lisp for writing temporary files. | |
| system:make-temp-file-name | &optional (prefix "temp") (directory(sys:temporary-directory)) | Returns an unused filename but does not create the file (so the same name could be returned by a subsequent call if the file is not created). |
| mkstemp | template | Like system:make-temp-file-name except it opens the file for output and returns the stream (rather than the filename). This operator is part of the new the new OSI interface (see Section 7.0 The Operating System Interface (OSI) module). |
| with-open-temp-file | (var template) &body body | Opens a temporary file named according to template while body is evaluated, and returns the name of the (now closed) file. This operator is part of the new the new OSI interface (see Section 7.0 The Operating System Interface (OSI) module). |
Allegro CL may be called with any number of arguments on the command line. Some of these arguments are used by Allegro CL itself (to suppress reading of initialization files, for example) and others are simply collected and made available to the running Lisp.
Lisp uses `--' as a delimiter between arguments used by Allegro CL when starting up and arguments simply collected and made available after Lisp has started. All arguments before the first appearance of `--' are used by Allegro CL and any improper arguments before that marker will cause Allegro CL to signal a warning. All arguments after the first appearance of `--' are ignored by Allegro CL when starting up and are available after startup, accessible with the following functions. Note that the arguments before the `--' are also available with these functions. Note too that Lisp can be created so it ignores all command-line arguments (simply making all available after startup). This will happen if an image is created with dumplisp with ignore-command-line-arguments specified as true.
Further, if no -I argument is provided (to specify an image file, so the image file with the same name and in the same directory as the executable is used), the command line will look like a -I argument was specified, as shown in the examples.
See with-command-line-arguments, which is a macro that can be used to process command-line arguments. See Command line arguments in startup.htm for information on command-line-arguments. The functions that access command-line arguments are shown in the following table. + arguments, which are Windows specific and affect how the executable starts up on Windows, are discarded and not included in the information returned returned by any of the command-line argument functions.
| Name | Arguments | Notes |
| system:command-line-argument | (n &key application) | Returns the value of the nth command-line arguments. |
| system:command-line-arguments | (&key application) | Returns a list of all command-line arguments. |
| system:command-line-argument-count | (&key application) | Returns the number of command-line arguments. |
The application keyword argument, if t
(the default) leaves out any arguments before the first `--' and
leaves out the `--' (so if `--' doesn't appear, the list containing
only the executable name is returned). If nil, all arguments are considered.
The purpose of these functions is to allow you to customize the running of Lisp when the image is invoked. As a simple example, suppose you invoke Lisp as follows:
mlisp -qq -- foo -batch bar
Here, mlisp is the name of the Allegro CL executable. Note
first that Lisp will not run in batch mode since the
-batch appears after `--'. However, no
initialization file will be read since the -qq
argument appears before the `--'. See startup.htm
for more information on command line arguments which affect how Lisp
starts up. As we said above, the command line arguments will show
-I <image.dxl> arguments even though they were not
specified.
Here is what the various command line functions return given that command line:
(sys:command-line-argument 0) [returns] "mlisp"
(sys:command-line-argument 1) [returns] "foo"
(sys:command-line-argument 1 :application nil) [returns] "-I"
(sys:command-line-arguments) [returns] ("mlisp" "foo"
"-batch" "bar")
(sys:command-line-arguments :application nil)
[returns] ("mlisp" "-I" "mlisp.dxl"
"-qq" "--" "foo" "-batch" "bar")
(sys:command-line-argument-count) [returns] 4
(sys:command-line-argument-count :application nil) [returns] 8
You may use this information as you see fit. One possible use, for example, is to have some function defined and run (perhaps in an initialization file) which takes some action (such as loading specific files) based on the values of the arguments.
The OSI interface (see Section 7.0 The Operating System Interface (OSI) module) includes more operators for setting, changing, and unsetting environment variables. These are described Appendix A.11 OSI miscellaneous low-level functionality.
The function sys:getenv returns (and with setf sets) the value of an environment variable. The functions setenv, putenv, and unsetenv set and unset environment variables. The function environment returns a list of environment variables and values in the original environment when Lisp was started (with later changes not reflected). These functions are in the OSI interface module mentioned above. Note that setenv and unsetenv are not supported on all operating systems (see the descriptions for details). sys:getenv and putenv are supported on all systems.
;; Here is an example using getenv and the new functions
;; setenv and unsetenv. It may be that the environment variables
;; exist on your system, in which case you will see different
;; values and may not wish to unset them. SETENV and UNSETENV
;; are not supported on all platforms.
cl-user(3): (getenv "FOO")
nil
cl-user(4): (setf (getenv "FOO") "bar")
"bar"
cl-user(5): (getenv "FOO")
"bar"
cl-user(6): (getenv "FOO2")
nil
cl-user(7): (putenv "FOO2=bar2")
t
cl-user(8): (getenv "FOO2")
"bar2"
cl-user(9): (unsetenv "FOO2")
t
cl-user(10): (getenv "FOO2")
nil
cl-user(11): (setenv "FOO2" "baz" t)
;;; overwrite (third argument) is t so does change value
t
cl-user(12): (getenv "FOO2")
"baz"
cl-user(13): (setenv "FOO2" "bazzzzzzzz" nil)
;;; overwrite (third argument) is nil so does not change value
t
cl-user(14): (getenv "FOO2")
"baz"
cl-user(15):
The next example show how to use sys:getenv and setf to set and reset environment variables on platforms that do not have setenv.
;; The current values of the environment variable on your system may, ;; of course, be different from what appears in this example. user(2): (sys:getenv "SHELL") "/bin/csh" user(3): (setf (sys:getenv "SHELL") "/bin/sh") "/bin/sh" user(4): (sys:getenv "SHELL") "/bin/sh"
Warning: If you use setf with sys:getenv to set an environment variable, the string specifying the new value is stored in malloc'ed space and that space cannot be freed (in any practical way). This creates a small memory leak in the system, but it should only be significant if you set many, many environment variables.
Prior to the release of the new OSI interface mentioned above, there was no pre-defined, programmatic way to unset an environment variable from within Lisp (on those platforms which supported unsetting environment variables). With the new module, on platforms that support it, unsetenv can be used.
The goal of the OSI module is to provide a Lisp layer for operating system services available on the platforms on which ACL runs. Most of the functions and macros in this module are modeled on system calls and library routines found in the UNIX manual (sections 2 and 3). The names of the functions in this module are usually the same as those found in the UNIX manual. The number and type of arguments are similar, however the interface to each system call and library routine was designed to be natural in Common Lisp so there are differences in number and type of arguments.
All of the items described here reside in the
:excl.osi package. You can load it with
(require :osi).
Many of the functions in this module are not available on Windows, for the simple reason that the system call or library routine is not available there. A few functions are not available on all UNIX versions on which Allegro CL runs, but most are. In all cases where a function is not available, an error of a specific type is signaled. The symbols for the functions which are not implemented are still exported from the modules' package.
Some of the functions here use system constants (e.g., R_OK). The naming of these constants is as follows: the name starts and ends with `*', has been converted to lower case, and `_' has been replaced with `-' (except leading `_'s are removed). This naming scheme is more Lisp-like and allows for the different case modes in Common Lisp.
There are a good number of system calls and library routines that take
file descriptors, returned by the open() system call. In an effort to
make this interface as natural in Lisp as possible, the corresponding
functions in this module take a stream instead of a file descriptor.
This means in general common-lisp:open should still be used to open
files. However, you may want to open a file with open(2) flags for
which there is no corresponding feature in Allegro CL (for example,
the flag O_EXCL). For this purpose, the function
os-open is provided. It also
returns a stream instead of a file descriptor.
Finally, there are large number of system calls and library routines. Not all of them are implemented in this module. Some do not really make sense in Lisp, or interfere with facilities already present. One such example in the latter category is signals. All the signal calls have been left out of this interface. ACL does have a native facility for handling signals (see the function add-signal-handler).
The Shell module provides Lisp versions of various shell commands. See shell-module.htm for details.
See Appendix A Operating System Interface Functionality for a list of functions, constants, etc. in the module. Subsections, grouped by functionality, contain the documentation pages. The functions etc. (except for those which already existed) do not have individual documentation pages. They are listed in the index and the permuted index. (The constants are not indexed, however.)
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 Appendix A.13 Lisp constants corresponding to Operating System constants). Note that they are are not indexed in the index.
Certain functions already existed (such as chdir). The symbols naming those functions
have been exported from the excl.osi package as
well as their home packages.
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 Appendix A.13 Lisp constants corresponding to Operating System constants and the separate document osi-constants.htm for a complete list of such constants. Note that not every constant is defined on every platform (architecture). In each definition, we say what platforms the constant is defined on. Then in Defined Operating System/Lisp constants by architecture in osi-constants.htm, we provide a list by platform of defined constants. We do not describe how the constants are used. Please look at the appropriate Operating System documentation for information on how these constants are used. (The operating system name, which differs from the Lisp name, is shown in each definition. You can search by the operating system name to find the corresponding Lisp name, if there is one.)
In an earlier version of the documentation, we did not name all defined constants and we mixed definitions of constants we did name with the related operators. In this version, we list all constants together, and list them all.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Arguments: filespec
Return information about the specified file,
filespec. The accessor functions stat-dev, stat-ino,
stat-mode, stat-nlink,
stat-uid, stat-gid,
stat-rdev, stat-size,
stat-atime,
stat-ctime and stat-mtime can
be used to retrieve specific information from the value returned by
this function. On failure an error of type syscall-error
is signaled.
NOTE: the values returned by stat-atime, stat-ctime and stat-mtime are universal times and not UNIX times. For information on conversion to/from universal and UNIX time see unix-to-universal-time and universal-to-unix-time. See Section 7.1 System calls and library routines dealing with time
Arguments: f
Accessor for the value returned by stat.
NOTE: the values returned by stat-atime, stat-ctime and stat-mtime are universal times and not UNIX times. For information on conversion to/from universal and UNIX time see unix-to-universal-time and universal-to-unix-time. See Section 7.1 System calls and library routines dealing with time
Arguments: f
Accessor for the value returned by stat.
NOTE: the values returned by stat-atime, stat-ctime and stat-mtime are universal times and not UNIX times. For information on conversion to/from universal and UNIX time see unix-to-universal-time and universal-to-unix-time. See Section 7.1 System calls and library routines dealing with time
Arguments: f
Accessor for the value returned by stat.
Arguments: f
Accessor for the value returned by stat.
Arguments: f
Accessor for the value returned by stat.
Arguments: f
Accessor for the value returned by stat.
Arguments: f
Accessor for the value returned by stat.
NOTE: the values returned by stat-atime, stat-ctime and stat-mtime are universal times and not UNIX times. For information on conversion to/from universal and UNIX time see unix-to-universal-time and universal-to-unix-time. See Section 7.1 System calls and library routines dealing with time
Arguments: f
Accessor for the value returned by stat.
Arguments: f
Accessor for the value returned by stat.
Arguments: f
Accessor for the value returned by stat.
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.
Arguments: f
Accessor for the value returned by stat.
Arguments: stream
This function is just like the function stat except that it operates on an open stream.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Arguments: dir
Close the directory handle associated with dir.
On failure signal an error of type syscall-error.
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.
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.
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.
Arguments: template
osi-not-supported.
This function creates a temporary directory and returns the name of the directory created (a string). The name of the file is determined by the template specified by template. template should end with six X's, which are replaced with a unique letter combination.
On failure an error of type syscall-error is signaled.
See the UNIX man page for mkdtemp(3) for more information on the system call associated with this function. It will tell you about things like the permissions on the new directory. The input string (template) is not modified and shares no space with the output string naming the new directory, which will be a newly-created string.
See also Section 4.0 Temporary directory and files.
;; 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):
Arguments: template
This function opens (for output) a stream on a temporary file and returns two values: the stream and the name of the file. The name of the file is determined by the template specified by template. template should end with six X's, which are replaced with the current process number and/or a unique letter combination. mkstemp, like the UNIX counterpart, is free of race conditions on opening the file.
On failure an error of type syscall-error is signaled.
This function is not supported on Windows, where it signals an error
of class osi-not-supported.
See also with-open-temp-file, mkdtemp, and Section 4.0 Temporary directory and files.
Arguments: (var template &key filename delete) &body body
This macro allows for safe use of temporary files, making sure they
are closed in the face of errors. It is also good for making sure
there are no race conditions on opening the file in the filesystem.
If an error occurs during the execution of body
then the open stream on the temporary file is closed
with :abort t given to common-lisp:close.
var should be a symbol which will by bound to the stream open to the file during the evaluation of body. The argument template is passed to mkstemp and should be a value suitable for the template argument to that function, that is a string ending in six X's. The beginning of the string (up to the X's) should be directory information plus whatever you want as the beginning of the temp file name, for example "/tmp/mytempXXXXXX".
The filename keyword argument, when
supplied, must be a symbol. The symbol will be bound during the
evaluation of the body to the actual filename that is used. The
delete keyword argument, if supplied and
non-nil, causes the file to be deleted after
the body completes (either normally or abnormally). Any errors that
may occur during file deletion are ignored.
The name of the temp file actually used is returned after body completes. The file is not deleted automatically after this macro completes unless delete is specified true. Here are a couple of examples:
cl-user(31): (excl.osi:with-open-temp-file (ss "/tmp/mytempXXXXXX")
(print 10 ss))
"/tmp/mytempRQaWrj"
cl-user(32): (shell "cat /tmp/mytempRQaWrj")
10 0
cl-user(33): (excl.osi:with-open-temp-file (ss "/tmp/mytempXXXXXX")
(print 10 ss)
(file-position ss 0)
(setq a (read ss)))
"/tmp/mytempSQaWrj"
cl-user(34): a
10
cl-user(35):
Because this macro uses mkstemp (which is not available on Windows), this macro is not supported on Windows.
Arguments: filespec
Break filespec into directory and filename components, returning the filename component. This is equivalent to
(file-namestring (pathname filespec))
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.
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.
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*.
Arguments:
Return the current working directory as a pathname. This function is the same as current-directory.
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.
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.
Arguments: filespec flags &optional mode
Open filespec for reading, writing or both. The
flags and mode arguments are
defined by the open(2) system call documentation on each system. The
value returned, if successful, is a Common Lisp stream. On failure an
error of type syscall-error is signaled.
The utility of os-open is for being able to use
open(2) flags for which there is no corresponding feature in Allegro.
O_EXCL is a good example of such a flag. Be aware
that using system specific flags will make your programs non-portable.
Consult the operating system documentation on the systems you care
about to make sure the flags in question exist on those platforms.
See with-os-open-file, which is a cl:with-open-file analog using os-open instead of cl:open to open the file.
Arguments: (var &rest rest os-open-args) &body body
This macro works like cl:with-open-file except it uses os-open instead of cl:open to open the file. It binds var to a stream returned by os-open, executes body and then closes the stream. This macro makes sure the stream is closed when the body exits, regardless of whether the exit is normal or non-local (i.e. caused by a throw or an error). os-open-args are given directly to os-open.
This macro was added to a module in a patch released around April 4, 2003. You must have updated (using sys:update-allegro) after that date for this macro to be defined.
Arguments: stream
The same as common-lisp:close,
provided for symmetry with os-open. (excl.osi:os-close
stream) is the same as (cl:close stream).
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.
Arguments: universal-time
Convert the argument universal-time to a UNIX time. See Section 7.1 System calls and library routines dealing with time for more information. See also unix-to-universal-time.
Arguments: unix-time
Convert the argument unix-time to a universal time. See Section 7.1 System calls and library routines dealing with time for more information. See also universal-to-unix-time.
Arguments: &optional ut
Return a string containing the time as of ut (which is a universal time) in the same format as the UNIX library routine ctime(3). In ACL, this is:
(locale-print-time ut :fmt "%a %b %d %T %Y")
Here are a couple of examples. They indicate that ut defaults to the current time, as returned by get-universal-time (the times differ by a few seconds because they were run sequentially).
cl-user(2): (excl.osi:ctime) "Thu Oct 24 10:11:30 2002" cl-user(3): (excl.osi:ctime (get-universal-time)) "Thu Oct 24 10:11:36 2002" cl-user(4):
See Section 7.1 System calls and library routines dealing with time for more information.
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.
Arguments: &rest args
This function closes the /etc/passwd file. See getpwent.
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.
Arguments: name
Get a pwent structure by name. See getpwent.
Arguments: uid
Get a pwent structure by uid. See getpwent.
Arguments: object
Return t if the argument is a pwent, nil otherwise. See getpwent.
Arguments: struct
Accessor for the pwent type. See getpwent.
Arguments: struct
Accessor for the pwent type. See getpwent.
Arguments: struct
Accessor for the pwent type. See getpwent.
Arguments: pwent
Accessor for the pwent type. See getpwent.
Arguments: pwent
Accessor for the pwent type. See getpwent.
Arguments: pwent
Accessor for the pwent type. See getpwent.
Arguments: pwent
Accessor for the pwent type. See getpwent.
Arguments:
Return t if shadow passwd support is
available on this version of Lisp.
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.
Arguments: &rest args
This function closes the shadow passwd file. See getspent and setspent.
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.
Arguments: name
Get a spwd structure by name. See getspent.
Arguments: object
Return t if the argument is a spwd, nil otherwise. See getspent.
Arguments: spwd
Accessor for the spwd type. See getspent.
Arguments: spwd
Accessor for the spwd type. See getspent.
Arguments: spwd
Accessor for the spwd type. See getspent.
Arguments: spwd
Accessor for the spwd type. See getspent.
Arguments: spwd
Accessor for the spwd type. See getspent.
Arguments: spwd
Accessor for the spwd type. See getspent.
Arguments: spwd
Accessor for the spwd type. See getspent.
Arguments: spwd
Accessor for the spwd type. See getspent.
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.
Arguments: &rest args
This function closes the group file. See getgrent.
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.
Arguments: object
Return t if the argument is a grent, nil otherwise. See getgrent.
Arguments: gid
Accessor for the grent type. See getgrent.
Arguments: gid
Accessor for the grent type. See getgrent.
Arguments: gid
Accessor for the grent type. See getgrent.
Arguments: gid
Accessor for the grent type. See getgrent.
Arguments: name
Get a grent structure by name. See getgrent.
Arguments: gid
Get a grent structure by uid. See getgrent.
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.
Arguments: &rest args
This function closes the networks file. See getnetent.
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.
Arguments: object
Return t if the argument is a netent, nil otherwise. See getnetent.
Arguments: netent
Accessor for the netent type. See getnetent.
Arguments: netent
Accessor for the netent type. See getnetent.
Arguments:
Arguments: netent
Accessor for the netent type. See getnetent.
Arguments: netent
Accessor for the netent type. See getnetent.
Arguments: name
Get a netent structure by name. See getnetent.
Arguments: net type
Get a netent structure by address and type. See getnetent.
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.
Arguments: &rest args
This function closes the services file. See getservent.
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.
Arguments: object
Return t if the argument is a servent,
nil otherwise. See getservent.
Arguments: servent
Accessor for the servent type. See getservent.
Arguments: servent
Accessor for the servent type. See getservent.
Arguments: servent
Accessor for the servent type. See getservent.
Arguments: servent
Accessor for the servent type. See getservent.
Arguments: name proto
Get a servent structure by name and protocol. See getservent.
Arguments: port proto
Get a servent structure by port and protocol. See getservent.
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.
Arguments: &rest args
This function closes the protocols file. See getprotoent.
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.
Arguments: object
Return t if the argument is a protoent,
nil otherwise. See getprotoent.
Arguments: protoent
Accessor for the protoent type. See getprotoent.
Arguments: protoent
Accessor for the protoent type. See getprotoent.
Arguments: protoent
Accessor for the protoent type. See getprotoent.
Arguments: name
Get a protoent structure by name. See getprotoent.
Arguments: proto
Get a protoent structure by protocol number. See getprotoent.
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.
Arguments: filespec argv &optional envp
Execute the program given by filespec with
arguments given by the argv and environment given
by envp. The currently running program is
replaced with the new program, so on success it does not return. On
failure an error of type syscall-error is signaled.
argv should be a list of strings, and envp a list of strings of the form "name=value". For example:
(execve "/bin/sh"
'("sh" "-c" "env")
'("FOO=bar" "BAZ=bam"))
which might print something like this:
BAZ=bam FOO=bar TERM=dumb HOSTTYPE=i386 PATH=/usr/local/bin:/bin:/usr/bin SHELL=/bin/csh OSTYPE=Linux SHLVL=1 _=/usr/bin/env
If envp is nil, then the
program is given the null environment.
For more information on this UNIX system call, see the execve(2) manual page.
Arguments: &key (mode nil)
Create and returns (as multiple values) a pair of streams, pointing
to a pipe. The first returned value is the input stream, used for
reading. The second returned value is the output stream, used for
writing. On failure an error of type syscall-error
is signaled.
mode is ignored on all but Windows, where it has
a meaning defined by the _pipe() documentation. The constants
_O_TEXT and _O_BINARY are
defined by this interface, as *o-text* and
*o-binary*.
Note: on Windows, the blocking behavior of pipes with respect to multiprocessing is currently unknown. Windows has a more common routine for creating pipes, CreatePipe(), but there is no interface to this routine at the current time.
This function was added after the initial release of the OSI interface. Please be sure you have updated with sys:update-allegro after February 10, 2003 to be sure this function is defined in your system.
Arguments: (invar outvar) &body body
Binds symbols invar (used for reading from the pipe) and outvar (used for writing to the pipe) to the streams returned by pipe. The macro makes sure the streams are closed when the macro body exits, either normally or in non-local exit situations (i.e., an error or throw). The body is allowed to close either or both streams, without causing an error or warning when the cleanup forms run after the body executes and try to close the streams.
This macro was added after the initial release of the OSI interface. Please be sure you have updated with sys:update-allegro after February 24, 2003 to be sure this function is defined in your system.
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.
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.
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.
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.
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.
Arguments:
The same as cuserid.
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.
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.
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.
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.
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.
Arguments:
Return the current process ID.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Arguments: pid
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:
Arguments:
Set the session 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.
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.
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.
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.
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 were added in an update made on approximately February 24, 2003. You must have updated with sys:update-allegro subsequent to that date for these arguments to be supported.
These arguments only have meaning on UNIX platforms. They are not supported on Windows.
uid and gid are numbers representing user and group ids. effective is a boolean which indicates that uid and gid are effective user and group ids. initgroups-user is a string naming a user.
Here is an example using command-output (which also has the new arguments):
cl-user(1): (require :osi)
; Fast loading /stuff1/acl/acl70/src/code/osi.fasl
t
cl-user(2): (excl.osi:command-output "whoami" :uid 483)
("layer")
nil
0
cl-user(3): (excl.osi:command-output "whoami")
("root")
nil
0
cl-user(4):
The gid, initgroups-user, and uid arguments are independent and are processed in the following order, using the indicated system calls (on most UNIX platforms):
| gid | setgid(), setegid() |
| initgroups-user | initgroups() |
| uid | setuid(), seteuid() |
The group is always set first, since after changing users that user may not have permission to change groups.
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):
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 were added in an update made on approximately February 24, 2003. You must have updated with sys:update-allegro subsequent to that date for these arguments to be supported.
These arguments only have meaning on UNIX platforms. They are not supported on Windows.
uid and gid are numbers representing user and group ids. effective is a boolean which indicates that uid and gid are effective user and group ids. initgroups-user is a string naming a user.
Here is an example using command-output (which also has the new arguments):
cl-user(1): (require :osi)
; Fast loading /stuff1/acl/acl70/src/code/osi.fasl
t
cl-user(2): (excl.osi:command-output "whoami" :uid 483)
("layer")
nil
0
cl-user(3): (excl.osi:command-output "whoami")
("root")
nil
0
cl-user(4):
The gid, initgroups-user, and uid arguments are independent and are processed in the following order, using the indicated system calls (on most UNIX platforms):
| gid | setgid(), setegid() |
| initgroups-user | initgroups() |
| uid | setuid(), seteuid() |
The group is always set first, since after changing users that user may not have permission to change groups.
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.
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.
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.
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.
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.
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.
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.
syscall-error
osi-not-supported
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.
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.
Arguments: syscall-error
An accessor for instances of syscall-error.
Arguments: errno format-string &rest format-args
Signal an error of type syscall-error, using
errno to construct an appropriate error message.
A condition class used for errors of unsupported functionality.
Arguments: mode
Set the file creation mask to mode and return the previous mask.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Arguments: (stream &key echo-newline) &body body
This macro disables terminal echo on stream, evaluates body, and then restores the prior terminal state. The terminal state is restored even if body finishes abnormally.
If echo-newline is true, newline characters will still be echoed. See below for an example of how that is sometimes useful.
Errors are ignored when attempting to disable/enable character echo. (Therefore, this macro works on Windows, although it has no effect on character echo).
The following example shows the use of with-terminal-echo-disabled with echo-newline nil and non-nil. In both cases, when the program prompted for the secret word, a word was typed, followed by the enter/return key. The word that was typed is not visible in the transcript due to terminal echo being successfully disabled. In the first call, "Thank You" appears on the same line as the prompt, because the user's enter/return keystroke was not echoed. In the second call, "Thank You" appears on a new line because the user's enter/return keystroke was echoed.
cl-user(2): (defun test-echo (arg)
(excl.osi:with-terminal-echo-disabled (*terminal-io*
:echo-newline arg)
(format t "Please type the secret word: ")
(read-line)
(format t "Thank you.~%")
t))
test-echo
cl-user(3): (test-echo nil)
Please type the secret word: Thank you.
t
cl-user(4): (test-echo t)
Please type the secret word:
Thank you.
t
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.
Arguments: errno
Returns a string describing the error code passed in errno, or an unknown error message if the error code is unknown.
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.
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.
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.
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.
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.
Arguments: val
Convert the long integer val from network byte order to host byte order.
Arguments: val
Convert the short integer val from network byte order to host byte order.
Arguments: val
Convert the long integer val from host byte order to network byte order.
Arguments: val
Convert the short integer val from host byte order to network byte order.
Arguments:
Return t if detach-from-terminal is supported
on this version of ACL, nil otherwise.
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.
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.
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*.
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.
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*.
Arguments: string
Return the value of the environment variable given by
string, or nil if it is
not defined.
The symbol naming this function is in the
system package and exported from the
excl.osi package. This function was defined in
Allegro CL prior to the release of the :osi
module. Its manual page is here.
See Section 6.0 Polling and setting environment variables.
Arguments: name value overwrite
Add name to the environment, with value
value, if it does not already exist. If it does
exist, change the value to value if
overwrite is non-nil,
leave it alone if overwrite is nil. On success t is
returned (leaving an existing value alone when
overwrite is nil is a
successful outcome). On failure an error of type syscall-error
is signaled.
This function is not supported on the following platforms, where it
signals an error of class
osi-not-supported:
See Section 6.0 Polling and setting environment variables.
Arguments: name
Remove environment variable name from the
environment. Always returns t.
This function is not supported on the following platforms, where it
signals an error of class
osi-not-supported:
See Section 6.0 Polling and setting environment variables.
Arguments: string
Add environment information as specifed by string, which has the form "name=value", adding or setting a variable name to value value.
(putenv "name=value")
is equivalent to
(setenv "name" "Value" t)
See setenv.
t is returned if the operation succeeds. If it fails,
an error of type syscall-error is signaled.
See Section 6.0 Polling and setting environment variables.
Arguments:
Return a list of the original environment when Lisp was started, each element of which has the form of (var . value). Any changes to the environment with setenv, putenv or setf of getenv are not reflected in the value returned by this function.
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.
Arguments: filespec1 filespec2
Return t if the files given by
filespec1 and filespec2 are
the same file, and nil otherwise.
Arguments: filespec1 filespec2
Return t if the files
filespec1 and filespec2
reside on the same filesystem, and nil otherwise.
Arguments: name
Return a pathname of the absolute pathname found when searching for
name in the directories given by the value of the
environment
variable PATH.
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.htm. Note that Not every constant is
defined on every platform (architecture).
osi-constants.htm has two sections:
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version | ||||||||