|
Allegro CL version 6.2 Significant update since 6.2 release. |
This document contains the following sections:
1.0 Operating-system interface
This chapter describes some functions in Allegro CL that interact with the host operating system. These functions include those providing access and control of system services, which, on UNIX and Linux, are typically found in chapters 2 and 3 of the UNIX manual.
A new module, :osi, was added after the release of Allegro CL 6.2.
The necessary files can be downloaded with update-allegro. The new 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 OSI module is available to all supported
customers. Certain updates which supply some of the functionality are available to all
customers.
Post 6.2 release update: 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):
Post 6.2 release update: 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/acl62/.
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/acl62/"
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:
Post 6.2 release note: the new :osi module, made available
after the initial release of Allegro CL 6.2, 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. The default value has also
changed. See the description page
for details. Also, two new keyword arguments have been added after the initial release of
Allegro CL 6.2. Again, see the description
page for details. 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. |
Post 6.2 release update: the new OSI interface (see Section 7.0 The Operating System Interface (OSI) module) includes operators like mkstemp 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 was added after the release of Allegro CL 6.2 and 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 was added after the release of Allegro CL 6.2 and 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:
| 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.
Post 6.2 release update: the new 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 new functions setenv, putenv, and unsetenv set and unset environment variables. The new functions are in the new 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 OSI module was added after the release of Allegro CL 6.2. The necessary files can be downloaded with update-allegro.
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, also added after the initial release of Allegro CL 6.2, 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, nor are they listed in the index.
Aside from defining new operators, etc., as described below, the OSI module patch does the following:
file-error condition is still a subclass of error,
but not a direct subclass. There is now an intervening class, excl::syscall-error,
which is exported from the :excl.osi package. t, (3) change the default of the if-does-not-exist argument
to :error, and (4) have the files removed in the proper order, so that
subdirectories are emptied before their parents. :always-append,
which causes O_APPEND to be used when opening the file. (This only has meaning for if-does-not-exist
when the file is opened for output.) This means that concurrent writes by any number of
programs will always write to the end of the file. This is useful for writting to log
files. Be warned, however, that changing the file position of a stream opened with :if-exists
:always-append or :if-does-not-exist :always-append will have no
effect. See the description of the implementation of cl:open
in Extensions to cl:make-package,
cl:disassemble, cl:open, cl:apropos in implementation.htm.
file-error condition, with proper errno information
when an error occurs. 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 single subsection, 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 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 Appendix A.14 Defined Operating System/Lisp constants by architecture, 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.
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 filespec 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 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 &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 filespec 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 filespec 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 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 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.2 System calls and library routines dealing with time
Arguments: f
Accessor for the value returned by stat.
NOTE: the values returned by stat-atime 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.2 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 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.2 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: 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. 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. 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. accepted.
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. accepted.
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. accepted.
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 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.
This function is not supported on Windows, where it signals an error of class osi-not-supported.
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 and Section 4.0 Temporary directory and files.
Arguments: (var template) &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. The return value is the name of the temp file used. If
an error occurs during the execution of body then the open stream on the temp file
is closed with the :abort t. The template should be keywords and
values acceptable to open, as with common-lisp:with-open-file.
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, 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: universal-time
Convert the argument universal-time to a UNIX time. See Section 7.2 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.2 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.2 System calls and library routines dealing with time for more information.
Arguments: &rest args
This function rewinds the file pointer to the beginning of /etc/passwd so getpwent can be used to iterate over all the entries.
Arguments: &rest args
This function closes the passwd file. See getpwent.
Arguments:
Return a pwent 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.
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 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.