33.1. System Calls

33.1.1. Networking
33.1.2. File system
33.1.3. Users and Groups
33.1.4. System Information
33.1.5. Mathematical functions
33.1.6. Encryption
33.1.7. Syslog
33.1.8. Processes
33.1.9. Accounting
33.1.10. Time conversion
33.1.11. String comparision
33.1.12. XTerm
33.1.13. Standard file input and output
33.1.14. Error handling
33.1.15. 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.1.1. Networking

(POSIX:RESOLVE-HOST-IPADDR &OPTIONAL host)

Returns the HOSTENT structure:

name
host name
aliases
LIST of aliases
addr-list
LIST of IP addresses as dotted quads (for IPv4) or coloned octets (for IPv6)
addrtype
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.1.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:

dev
Device ID of device containing file.
ino
File serial number.
mode
Mode of file.
nlink
Number of hard links to the file.
uid
User ID of file.
gid
Group ID of file.
rdev
Device ID (if file is character or block special).
size
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.
atime
universal time of last access.
mtime
universal time of last data modification.
ctime
universal time of last status change (on Win32 - creation time).
blksize
A file system-specific preferred I/O block size for this object. In some file system types, this may vary from file to file.
blocks
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.

(POSIX:SET-FILE-STAT pathname &KEY :ATIME :MTIME :MODE :UID :GID)
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:

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

All slots are read-only.

(OS:FILE-INFO pathname &OPTIONAL all)

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

attributes
ctime
atime
wtime
size
name
name-short

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.

(POSIX:STREAM-LOCK stream lock-p &KEY (:BLOCK T) (:SHARED NIL) (:START 0) (:END NIL))

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.

Warning

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

Warning

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.
(POSIX:FILE-SIZE file)
(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.
(POSIX:CONVERT-MODE mode)
Convert between numeric, (e.g., 0644) and symbolic (e.g., (:RUSR :WUSR :RGRP :ROTH)) file modes.
(POSIX:UMASK mode)
Change process mask using umask.
(POSIX:COPY-FILE source destination &KEY :METHOD :PRESERVE :IF-EXISTS :IF-DOES-NOT-EXIST)

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.

(POSIX:DUPLICATE-HANDLE fd1 &OPTIONAL fd2)
This is an interface to the dup system calls on UNIX systems and to DuplicateHandle system call on Win32.
(OS:SHORTCUT-INFO pathname)
Return information about a Win32 shortcut (#P".lnk") file contents in a SHORTCUT-INFO structure.
(OS:MAKE-SHORTCUT pathname &KEY :WORKING-DIRECTORY :ARGUMENTS :SHOW-COMMAND :ICON :DESCRIPTION :HOT-KEY :PATH)
Create (or modify the properties of an existing one) a Win32 shortcut (#P".lnk") file.
(OS:FILE-PROPERTIES filename set &KEY :INITID &ALLOW-OTHER-KEYS)

Wrapper for the Win32 IPropertyStorage functionality.

filename
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.
set
property set, either :BUILT-IN or :USER-DEFINED
:INITID init-id
set the init-id
specifier value
specifier

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

INTEGER
a property identifier
KEYWORD

Predefined KEYWORD IDs are

:APPNAME:CREATE-DTM:LASTPRINTED:SUBJECT
:AUTHOR:DOC-SECURITY:LASTSAVE-DTM:TEMPLATE
:CHARCOUNT:EDITTIME:LOCALE:THUMBNAIL
:CODEPAGE:KEYWORDS:PAGECOUNT:TITLE
:COMMENTS:LASTAUTHOR:REVNUMBER:WORDCOUNT
STRING
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.
(INTEGER|KEYWORD STRING)
the first element is used as a specifier, the string is associated with this ID.

value

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

:BOOL:I1:LPWSTR:UI4
:BSTR:I2:R4:UI8
:DATE:I4:R8:UINT
:ERROR:I8:UI1 
:FILETIME:LPSTR:UI2 

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.

(POSIX:MKSTEMP filename &KEY :DIRECTION :ELEMENT-TYPE :EXTERNAL-FORMAT :BUFFERED)

Calls mkstemp, returns a FILE-STREAM.

:DIRECTION should allow output.

When mkstemp is missing, use tempnam. On Win32 use GetTempFileName.

(POSIX:MKDTEMP filename)
Calls mkdtemp (similar to mkstemp but not in POSIX), returns the namestring of a new empty temporary directory.
(POSIX:SYNC &OPTIONAL stream)
Calls fsync (FlushFileBuffers on Win32) on the file descriptor associated with stream, or sync when stream is not supplied

33.1.3. Users and Groups

(POSIX:USER-INFO &OPTIONAL user)

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.

(POSIX:GROUP-INFO &OPTIONAL group)

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.

(POSIX:USER-SHELLS)
Call getusershell.
(OS:GET-USER-SID &OPTIONAL user)
Call LookupAccountName on user or, if that is not supplied, call OpenProcessToken GetTokenInformation, and then ConvertSidToStringSid on User.Sid.

33.1.4. System Information

(POSIX:UNAME)
Return a structure describing the OS, derived from uname.
(POSIX:SYSCONF &OPTIONAL what)
(POSIX:CONFSTR &OPTIONAL what)
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.
(POSIX:PATHCONF pathname &OPTIONAL what)
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.
(POSIX:RLIMIT &OPTIONAL what)
Return the current and the maximal limits as two values when what is specified or the association 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-alist)

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-alist is an association list, as returned by (POSIX:RLIMIT).
(POSIX:USAGE)
Return 2 structures describing the resource usage by the lisp process and its children, using getrusage.
(POSIX:BOGOMIPS)
Compute the BogoMips rating.
(POSIX:LOADAVG &OPTIONAL percentp)
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.
(OS:SYSTEM-INFO)
Return Win32 system information in a SYSTEM-INFO structure.
(OS:VERSION)
Return Win32 version information in a VERSION structure.
(OS:MEMORY-STATUS)
Return Win32 memory status information in a MEMORY-STATUS structure.
(OS:PHYSICAL-MEMORY)

Return 2 values: total and available physical memory.

Platform Dependent: UNIX, Win32 platforms only.

(OS:HOSTID)
(SETF (OS:HOSTID) value)

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

Warning

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))
⇒ "7.3.192.168"
(first (posix:hostent-addr-list (POSIX:RESOLVE-HOST-IPADDR :default)))
⇒ "192.168.7.3"

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.

(OS:DOMAINNAME)
(SETF (OS:DOMAINNAME) domain)
Call getdomainname and setdomainname.

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

Warning

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

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

33.1.7. Syslog

(POSIX:OPENLOG ident &KEY :PID :CONS :NDELAY :ODELAY :NOWAIT :FACILITY)
Calls openlog
(POSIX:SETLOGMASK maskpri)
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.

(POSIX:CLOSELOG)
Calls closelog.

33.1.8. Processes

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

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

:REALTIME:NORMAL:IDLE
:HIGH:BELOW-NORMAL 
:ABOVE-NORMAL:LOW 

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

(POSIX:KILL pid signal)
Calls kill.
(POSIX:GETPPID)
Calls getppid.
(POSIX:GETPGRP)
Calls getpgrp.
(POSIX:SETPGRP)
Calls setpgrp; on non-POSIX systems where it requires 2 arguments (legacy BSD-style), it is called as setpgrp(0,0).
(POSIX:GETSID pid)
Calls getsid.
(POSIX:SETSID)
Calls setsid.
(POSIX:PGID pid)
(SETF (POSIX:PGID pid) pgid)
Call getpgid and setpgid.
(POSIX:SETREUID ruid euid)
Call setreuid.
(POSIX:SETREGID rgid egid)
Call setregid.
(POSIX:UID)
(SETF (POSIX:UID) uid)
Call getuid and setuid.
(POSIX:GID)
(SETF (POSIX:GID) gid)
Call getgid and setgid.
(POSIX:EUID)
(SETF (POSIX:EUID) uid)
Call geteuid and seteuid.
(POSIX:EGID)
(SETF (POSIX:EGID) gid)
Call getegid and setegid.
(POSIX:GROUPS)
(SETF (POSIX:GROUPS) list)
Call getgroups and setgroups.
(POSIX:WAIT &KEY :PID :USAGE :NOHANG :UNTRACED :STOPPED :EXITED :CONTINUED :NOWAIT)

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

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

33.1.9. Accounting

(POSIX:ENDUTXENT)
Calls endutxent.
(POSIX:GETUTXENT &OPTIONAL utmpx)
Calls getutxent, returns a STRUCTURE-OBJECT of type POSIX:UTMPX, which can be passed to subsequent calls to this function and re-used.
(POSIX:GETUTXID id)
Calls getutxid, the argument is filled and returned.
(POSIX:GETUTXLINE line)
Calls getutxline, the argument is filled and returned.
(POSIX:PUTUTXLINE utmpx)
Calls pututxline, the argument is filled and returned.
(POSIX:SETUTXENT)
Calls setutxent.

33.1.10. Time conversion

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

33.1.11. String comparision

Functions

(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.1.12. 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 *ERROR-OUTPUT*
      (SETQ *DEBUG-IO*
            (POSIX:MAKE-XTERM-IO-STREAM :title "clisp errors and debug")))

Platform Dependent: UNIX platform only.

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

Functions

OS:FOPEN
OS:FDOPEN
OS:FREOPEN
OS:FCLOSE
OS:FFLUSH
OS:FILENO

may SIGNAL an ERROR.

Return values

OS:FOPEN
OS:FDOPEN
FFI:file = FFI:FOREIGN-POINTER
OS:FREOPEN
OS:FCLOSE
OS:FFLUSH
OS:CLEARERR
no values (they modify their file argument in place)
OS:FEOF
OS:FERROR
BOOLEAN
OS:FILENO
INTEGER (file descriptor)

We also define 3 constants

OS:STDIN
OS:STDOUT
OS:STDERR

Note

This functionality is not for i/o, but merely for for 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.

This functionality is only present if FFI is present.

33.1.14. Error handling

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

(OS:ERRNO &OPTIONAL error-code)

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

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.

On Win32, GetLastError and SetLastError are used instead of errno.

(OS:STRERROR &OPTIONAL error-code)

Return a string description of error-code. When error-code is not supplied, errno (GetLastError on Win32) is used.

This calls strerror on UNIX and FormatMessage on Win32.

This functionality is only present if FFI is present.

33.1.15. Miscellanea

(OS:CLIPBOARD)
(SETF (OS:CLIPBOARD) object)

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.49Last modified: 2010-07-07