33.2. System Calls

33.2.1. Networking
33.2.2. File system
33.2.3. Users and Groups
33.2.4. System Information
33.2.5. Mathematical functions
33.2.6. Encryption
33.2.7. Syslog
33.2.8. Processes
33.2.9. Accounting
33.2.10. Time and Data Conversion
33.2.11. String comparision
33.2.12. Wildcard Matching
33.2.13. XTerm
33.2.14. Standard file input and output
33.2.15. Error handling
33.2.16. Miscellanea

The POSIX module makes some system calls available from lisp. Not all of these system calls are actually POSIX, so this package has a nickname OS. If the package prefix is not specified below, the symbol resides in this package.

This module is present in the base linking set by default.

When this module is present, *FEATURES* contains the symbol :SYSCALLS.

33.2.1. Networking


Returns the HOSTENT structure:

host name
LIST of aliases
LIST of IP addresses as dotted quads (for IPv4) or coloned octets (for IPv6)
INTEGER address type (IPv4 or IPv6)

When host is omitted or :DEFAULT, return the data for the current host. When host is NIL, all the host database is returned as a list (this would be the contents of the /etc/hosts file on a UNIX system or ${windir}/system32/etc/hosts on a Win32 system).

This is an interface to gethostent, gethostbyname, and gethostbyaddr.

(OS:SERVICE &OPTIONAL service-name protocol)

A convenience function for looking up a port given the service name, such as WWW or FTP. It returns the SERVICE structure (name, list of aliases, port, protocol) for the given service-name and protocol, or all services as a LIST if service-name is missing or NIL.

This is an interface to getservent, getservbyname, and getservbyport.

33.2.2. File system

(POSIX:FILE-STAT pathname &OPTIONAL link-p)

Return the FILE-STAT structure. pathname can be a STREAM, a PATHNAME, a STRING or a NUMBER (on a UNIX system, meaning file descriptor). The first slot of the structure returned is the string or the number on which stat, fstat, or lstat was called. The other slots are numbers, members of the struct stat:

Device ID of device containing file.
File serial number.
Mode of file.
Number of hard links to the file.
User ID of file.
Group ID of file.
Device ID (if file is character or block special).
For regular files, the file size in bytes. For symbolic links, the length in bytes of the pathname contained in the symbolic link. For a shared memory object, the length in bytes. For a typed memory object, the length in bytes. For other file types, the use of this field is unspecified.
universal time of last access.
universal time of last data modification.
universal time of last status change (on Win32 - creation time).
A file system-specific preferred I/O block size for this object. In some file system types, this may vary from file to file.
Number of blocks allocated for this object.

All slots are read-only.

If the system does not support a particular field (e.g., Win32 prior to 2000 does not have hard links), NIL (or the default, like 1 for the number of hard links for old Win32) is returned.

Win32 platform only.

Normally, one would expect (POSIX:FILE-STAT "foo") and (POSIX:FILE-STAT (OPEN "foo")) to return similar objects (OPENing a file changes its access time though). This is not the case on Win32, where stat works but fstat does not. Specifically, fstat requires an int argument of an unknown nature, and it is not clear how do deduce it from the Win32 file handle. Therefore, instead of always failing on open FILE-STREAM arguments, this function calls GetFileInformationByHandle and fills the FILE-STAT return value based on that.

Set some file attributes using chmod, chown, and utime.
(POSIX:STAT-VFS pathname)

Return a STAT-VFS structure. pathname can be a STREAM, a PATHNAME, a STRING or a NUMBER (on a UNIX system, meaning file descriptor). The first slot of the structure returned is the string or the number on which statvfs or fstatvfs was called. The other slots are members of the struct statvfs:

File system block size.
Fundamental file system block size.
Total number of blocks on file system in units of frsize.
Total number of free blocks.
Number of free blocks available to non-privileged processes.
Total number of file serial numbers.
Total number of free file serial numbers.
Number of file serial numbers available to non-privileged processes.
File system ID.
List of platform-dependent values, such as :READ-ONLY.
Maximum filename length.
Volume name (Win32 only).
File system type (Win32 only).

All slots are read-only.

(POSIX:CHROOT pathname)

Change the apparent disk root directory for the current running process (and its children) using chroot.

Unless the process has superuser privileges, the operation will probably fail with EPERM.


For each object under pathname calls function with 5 arguments:

  1. the pathname of the object
  2. the FILE-STAT instance containing information on the object (or NIL, see below)
  3. a keyword giving additional information. Its value is one of the following:

    The object is a file.
    The object is a directory.
    The object is a directory and subdirectories have been visited. (This condition shall only occur if the :DEPTH argument is non-NIL.)
    The object is a symbolic link. (This condition shall only occur if the PHYS argument is non-NIL.)
    The object is a symbolic link that does not name an existing file. (This condition shall only occur if the PHYS argument is NIL.)
    The object is a directory that cannot be read. The fn function shall not be called for any of its descendants.
    The stat function failed on the object because of lack of appropriate permission. The FILE-STAT argument is NIL. If stat fails for any other reason, and ERROR is SIGNALed.

  4. the offset of the object's filename in the pathname passed as the first argument to function.
  5. the depth relative to the root of the walk, where the root level is 0.

As soon as function returns non-NIL, this function returns that value; if function always returns NIL, then this function also returns NIL when the file tree is exhausted.

The :FD-LIMIT argument defaults to 5.

If :CHDIR argument is non-NIL, the function shall change the current working directory to each directory as it reports files in that directory

If :DEPTH argument is non-NIL, the function shall report all files in a directory before reporting the directory itself.

If :MOUNT argument is non-NIL, the function shall only report files in the same file system as pathname.

If :PHYS argument is non-NIL, the function shall perform a physical walk and shall not follow symbolic links.

Calls nftw.

(OS:FILE-INFO pathname &OPTIONAL all)

Return the FILE-INFO structure. pathname should be a pathname designator. The 7 slots are


When pathname is wild, returns just the first match, unless the second (optional) argument is non-NIL, in which case a LIST of objects is returned, one for each match.


Set or remove a file lock for the (portion of the) file associated with stream, depending on lock-p. When block is NIL, the call is non-blocking, and when locking fails, it returns NIL. When shared is non-NIL, then lock can be shared between several callers. Several processes can set a shared (i.e., read) lock, but only one can set an exclusive (i.e., write, or non-shared) lock. Uses fcntl or LockFileEx.


UNIX and Win32 differ on locking 0-length files: on Win32, two processes can have exclusive locks on it!


Win32 locks are mandatory: if you lock a file, others will not be able to open it! UNIX locks are usually advisory: a process is free to ignore it, but on some UNIX systems one can mount some file system with mandatory locks.

(POSIX:WITH-STREAM-LOCK (stream &REST options) &BODY body)
Lock the stream, execute the body, unlock the stream. Pass options to POSIX:STREAM-LOCK.
(POSIX:STREAM-OPTIONS stream command &OPTIONAL value)

Call fcntl, command can be :FD or :FL.

When value is missing, the option is queried and the value is returned; if value is supplied, the option is set and no values are returned.

(SETF (POSIX:FILE-SIZE file) size)

Extend FILE-LENGTH to operate on pathname designators.

Set the size of a file using ftruncate (if file is an open FILE-STREAM) or truncate (if file is a pathname designator).

Use SetFilePointerEx and SetEndOfFile on Win32.

(POSIX:MKNOD pathname type mode)
Create a special file using mknod. Use :FIFO to create pipes and :SOCK to create sockets.
Convert between numeric, (e.g., 0644) and symbolic (e.g., (:RUSR :WUSR :RGRP :ROTH)) file modes.
Change process mask using umask.

This is an interface to symlink (when method is :SYMLINK), link (when it is :HARDLINK), and rename (when it is :RENAME) system calls, as well as, you guessed it, a generic file copy utility (when method is :COPY).

When method is :HARDLINK-OR-COPY and link fails (e.g., because the source and destination are on different devices), fall back to :COPY.

Both source and destination may be wild, in which case TRANSLATE-PATHNAME is used.

The meaning and defaults of :IF-EXISTS and :IF-DOES-NOT-EXIST are the same as in OPEN.

This is an interface to the dup system calls on UNIX systems and to DuplicateHandle system call on Win32.
Return information about a Win32 shortcut (#P".lnk") file contents in a SHORTCUT-INFO structure.
Create (or modify the properties of an existing one) a Win32 shortcut (#P".lnk") file.

Wrapper for the Win32 IPropertyStorage functionality.

name of a compound file (where properties are stored) or (on NTFS) name of any file (properties are stored in the filesystem). For compound files on NTFS, file storage is preferred.
property set, either :BUILT-IN or :USER-DEFINED
:INITID init-id
set the init-id
specifier value

the property specifier: an INTEGER, KEYWORD, STRING or a LIST of an INTEGER or a KEYWORD and a STRING.

a property identifier

Predefined KEYWORD IDs are

string property specifier. If no match is found, the first ID >= init-id (which defaults to 2) is associated with the string and its value is replaced with new value.
the first element is used as a specifier, the string is associated with this ID.


the new value of the property, a suitable Lisp object, NIL or a LIST of a KEYWORD and the value itself. If value is NIL, no assignment is done. :EMPTY and :NULL correspond to the VT_EMPTY and VT_NULL data types. KEYWORD in the LIST specifies the desired type of the property being set. Supported types are


FILETIMEs are converted to/from the universal time format, while DATEs are not.

Returns the property contents before assignment as multiple values.

(OS:FILE-OWNER filename)

Return the owner of the file.

Platform Dependent: UNIX, Win32 platforms only.


Calls mkstemp; returns a FILE-STREAM.

:DIRECTION should allow output.

(POSIX:MKDTEMP filename)
Calls mkdtemp; creates a new empty temporary directory and returns its namestring.
Calls fsync (FlushFileBuffers on Win32) on the file descriptor associated with stream, or sync when stream is not supplied

33.2.3. Users and Groups


Return the USER-INFO structure (name, encoded password, UID, GID, full name, home directory, shell). user should be a STRING (getpwnam is used) or an INTEGER (getpwuid is used). When user is missing or NIL, return all users (using getpwent). When user is :DEFAULT, return the information about the current user (using getlogin).

Platform Dependent: UNIX platform only.


Return the GROUP-INFO structure (name, GID, member LIST). group should be a STRING (getgrnam is used) or an INTEGER (getgrgid is used). When group is missing or NIL, return all groups (using getgrent).

Platform Dependent: UNIX platform only.

Call getusershell.
Call LookupAccountName on user or, if that is not supplied, call OpenProcessToken, GetTokenInformation, and then ConvertSidToStringSid on User.Sid.

33.2.4. System Information

Return a structure describing the OS, derived from uname.
Return the specified configuration parameter or a property list of all available parameters (when what is missing or NIL), by calling sysconf and confstr respectively.
Return the specified configuration parameter or a property list of all available parameters (when what is missing or NIL), by calling fpathconf on open file streams and pathconf on all other pathname designators.
Return the current and the maximal limits as two values when what is specified or the property list of all available limits (as an RLIMIT structure) when what is missing or NIL, by calling getrlimit.
(SETF (POSIX:RLIMIT what) (VALUES cur max))
(SETF (POSIX:RLIMIT what) rlimit)
(SETF (POSIX:RLIMIT) rlimit-plist)

Set the limits using setrlimit.

  1. In the first form, cur and max are numbers (or NIL for RLIM_INFINITY).
  2. In the second form, rlimit is an RLIMIT structure.
  3. In the third form, rlimit-plist is a property list, as returned by (POSIX:RLIMIT).
Return the USAGE structure describing the resource usage of the thread, process, or its children, using getrusage. WHen what is missing or NIL, return all available data as a property list.
Compute the BogoMips rating.
Return 1, 5, and 15 minute system load averages, retrieved by getloadavg. If the argument is specified and non-NIL, the values are returned as integer percentiles.
Return Win32 system information in a SYSTEM-INFO structure.
Return Win32 version information in a VERSION structure.
Return Win32 memory status information in a MEMORY-STATUS structure.

Return 2 values: total and available physical memory.

Platform Dependent: UNIX, Win32 platforms only.

(SETF (OS:HOSTID) value)

Call gethostid and return a (hopefully) universally unique INTEGER identifier of this machine.


On Linux this number appears to be the IPv4 32-bit address with the first 2 bytes and the last 2 bytes swapped:

(RAWSOCK:CONVERT-ADDRESS :inet (os:hostid))
⇒ ""
(first (posix:hostent-addr-list (POSIX:RESOLVE-HOST-IPADDR :default)))
⇒ ""

This, of course, means that universally unique it is not.

Superuser can also set host identifier using SETF which calls sethostid.

Platform Dependent: UNIX, Win32 platforms only.

Call getdomainname and setdomainname.

33.2.5. Mathematical functions

We implement access to

(erf real)
(erfc real)
(j0 real)
(j1 real)
(jn integer real)
(y0 real)
(y1 real)
(yn integer real)
(tgamma real)
(lgamma real)

which compute the error functions, Bessel functions and Gamma.

These functions are required by the POSIX standard and should be declared in <math.h>.


Please note that these functions do not provide lisp-style error handling and precision, and do all the computations at the DOUBLE-FLOAT level.

Function (ffs n) finds the first bit set. It is implemented in pure Lisp and supports BIGNUMs.

33.2.6. Encryption

(POSIX:CRYPT key salt)
Call crypt, arguments are STRINGs.
(POSIX:ENCRYPT block decrypt-p)
Call encrypt and setkey, respectively. block and key are of type (VECTOR (UNSIGNED-BYTE 8) 8). decrypt-p is BOOLEAN.

33.2.7. Syslog

Calls openlog
Calls setlogmask.
(POSIX:SYSLOG severity facility format-string &REST arguments)

Calls syslog on (APPLY FORMAT NIL format-string arguments).

No % conversion is performed, you must do all formatting in Lisp.

Calls closelog.

33.2.8. Processes

Return the process ID (on UNIX calls getpid, on Win32 calls GetCurrentProcessId)
(SETF (OS:PRIORITY pid &OPTIONAL what) priority)

Return or set the process priority, platform-dependent INTEGER or platform-independent SYMBOL, one of


On UNIX calls getpriority and setpriority, on Win32 calls GetPriorityClass and SetPriorityClass.

(POSIX:KILL pid signal)
Calls kill.
Calls getppid.
Calls getpgrp.
Calls setpgrp; on non-POSIX systems where it requires 2 arguments (legacy BSD-style), it is called as setpgrp(0,0).
Calls getsid.
Calls setsid.
(SETF (POSIX:PGID pid) pgid)
Call getpgid and setpgid.
(POSIX:SETREUID ruid euid)
Call setreuid.
(POSIX:SETREGID rgid egid)
Call setregid.
Call getuid and setuid.
Call getgid and setgid.
Call geteuid and seteuid.
Call getegid and setegid.
Call getgroups and setgroups.

Wait for termination of the child process :PID (or any child process if not specified).

If :NOHANG is specifed, return 0 as the only value immediately if no child process has terminated.

Otherwise, the first return value is the pid of the terminated child process.

The second and third return values depend on the way the process terminated:

2nd value = :EXITED
3rd value = exit status
if the child terminated normally, e.g., by calling exit.
2nd value = :SIGNALED
3rd value = signal
if the child process was terminated by a signal.
2nd value = :STOPPED
3rd value = signal
if the child process was stopped by delivery of a signal.
2nd value = :CONTINUED
3rd value = NIL
if the child process has continued from a job control stop.
2nd value = NIL
3rd value = number
if CLISP could not figure out what has happened. Please read your local waitpid manual and send us a patch.

The fourth value is only returned if :USAGE is non-NIL and in that case it is a structure describing resource usage by the terminated process, similar to what POSIX:USAGE returns.

To avoid race conditions, it is important to start your subprocesses and POSIX:WAIT for them inside the body of a POSIX:WITH-SUBPROCESSES form.

Calls waitpid and (when the :USAGE argument is non-NIL) wait4.

Evaluate body while receiving signals from subprocesses; your EXT:RUN-PROGRAM and related POSIX:WAIT calls should be inside it.

33.2.9. Accounting

Calls endutxent.
Calls getutxent, returns a STRUCTURE-OBJECT of type POSIX:UTMPX, which can be passed to subsequent calls to this function and re-used.
Calls getutxid, the argument is filled and returned.
Calls getutxline, the argument is filled and returned.
Calls pututxline, the argument is filled and returned.
Calls setutxent.

33.2.10. Time and Data Conversion

(OS:STRING-TIME format-string &OPTIONAL object timezone)
(OS:GETDATE string &OPTIONAL timezone)

Parse the string into a universal time using getdate.

If the the environment variable DATEMSK is not set when CLISP is invoked, CLISP sets it to point to the file modules/syscalls/datemsk, installed as (MERGE-PATHNAMES "syscalls/datemsk" CUSTOM:*LIB-DIRECTORY*).

33.2.11. String comparision


(OS:VERSION< x1 x2)
(OS:VERSION<= x1 x2)
(OS:VERSION> x1 x2)
(OS:VERSION>= x1 x2)

compare two STRINGs as version numbers (e.g., "foo10" is greater than "foo9") using strverscmp and return a BOOLEAN.

Function OS:VERSION-COMPARE does the same but returns either <, > or =.

33.2.12. Wildcard Matching

Wildcards describe sets of file names; see Pathname Matching Notation for the syntax description.

(POSIX:FNMATCH pattern string &KEY :PATHNAME :PERIOD :NOESCAPE (:CASE-SENSITIVE T))This function returns a non-NIL value if the string matches the pattern by calling fnmatch.

(POSIX:FNMATCH-MATCHER pattern)This function is a valid value for CUSTOM:*APROPOS-MATCHER*.


These two functions used to reside in a separate package WILDCARD, which has been now deprecated.

33.2.13. XTerm

(POSIX:MAKE-XTERM-IO-STREAM &KEY title xterm) When running under the X Window System, you can create a bidirectional STREAM, which uses a new dedicated text window (created by the executable specified by the :XTERM argument which should be compatible with xterm and rxvt, i.e., accept options -n, -T, and -e) using the function POSIX:MAKE-XTERM-IO-STREAM:

      (SETQ *DEBUG-IO*
            (POSIX:MAKE-XTERM-IO-STREAM :title "clisp errors and debug")))

Platform Dependent: UNIX platform only.

33.2.14. Standard file input and output

We define the type FFI:file = FFI:FOREIGN-POINTER and the following functions:

(fopen filename mode)
(fdopen fd mode)
(freopen filename mode file)
(fclose file)
(fflush file)
(clearerr file)
(feof file)
(ferror file)
(fileno file)

call their namesakes defined in <stdio.h>.




Return values

no values (they modify their file argument in place)
INTEGER (file descriptor)

We also define 3 constants



Iterface to foreign libraries. This functionality can be used by FFI modules which interface to functions which use the C FILE* pointers. E.g., postgresql has a function PQtrace which expects a FILE* argument. You can use OS:FOPEN and OS:FCLOSE for that.

Bypass Common Lisp filename processing. You can also use this functionality to access files whose names are interpreted as wild by Common Lisp. E.g.,

(LET ((file (posix:fopen "foo*" "r")))
      (WITH-OPEN-STREAM (s (EXT:MAKE-STREAM (posix:fileno file)))
        (READ-LINE s))
    (posix:fclose file)))

33.2.15. Error handling

To handle errors in foreign functions, the following four functions are provided:


When error-code is supplied, errno is set (useful before a system call which sets errno as the only way to report an error).

If error-code is a NUMBER, the corresponding KEYWORD is returned and vice versa.

When error-code is not supplied, the current errno is returned as a keyword if possible, a number otherwise.

When error-code is T, all known error codes are returned as an association list.


Just like POSIX:ERRNO, but uses GetLastError and SetLastError instead of errno.

Platform Dependent: Win32 platform only.


Return a string description of error-code. When error-code is not supplied, errno is used.

This calls strerror.


Just like POSIX:STRERROR, but uses FormatMessage and GetLastError.

Platform Dependent: Win32 platform only.

33.2.16. Miscellanea


Get (using GetClipboardData) a set (using SetClipboardData) the windows clipboard.

Return a STRING; convert object to a STRING using PRINC-TO-STRING.

Platform Dependent: Win32 and Cygwin platforms only.

These notes document CLISP version 2.49+Last modified: 2012-05-04