32.11. System Calls

32.11. System Calls
Prev	Chapter 32. Extensions Implemented as Modules	Next

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

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

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

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

(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: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 or getuid).

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

In the first form, cur and max are numbers (or NIL for RLIM_INFINITY).
In the second form, rlimit is an RLIMIT structure.
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:ERF real) (POSIX:ERFC real) (POSIX:J0 real) (POSIX:J1 real) (POSIX:JN integer real) (POSIX:Y0 real) (POSIX:Y1 real) (POSIX:YN integer real) (POSIX:GAMMA real) (POSIX:LGAMMA real)

Compute the error functions, Bessel functions and Gamma. These functions are required by the POSIX standard and should be available in libm.so.

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.

(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: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.

(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).

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

(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: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: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.

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

(OS:PHYSICAL-MEMORY)

Return 2 values: total and available physical memory.

Platform Dependent: UNIX, Win32 platforms only.

(OS:FILE-OWNER filename)

Return the owner of the file.

Platform Dependent: UNIX, Win32 platforms only.

(OS:PRIORITY pid &OPTIONAL what)

Return 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, on Win32 calls GetPriorityClass.

SETFable using setpriority and SetPriorityClass.

(OS:PROCESS-ID)

Return the process ID (on UNIX calls getpid, on Win32 calls GetCurrentProcessId)

(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

(POSIX:KILL pid signal)

calls kill

(POSIX:GETPGRP pid)

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:SETPGID pid pgid)

calls setpgid

(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

(POSIX:GETUID) (SETF (POSIX:GETUID) uid)

Call getuid and setuid.

(POSIX:GETGID) (SETF (POSIX:GETGID) gid)

Call getgid and setgid.

(POSIX:GETEUID) (SETF (POSIX:GETEUID) uid)

Call geteuid and seteuid.

(POSIX:GETEGID) (SETF (POSIX:GETEGID) gid)

Call getegid and setegid.

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

When object is a STRING, is is parsed according to format-string by strptime. When it is an INTEGER, it is formatted according to format-string by strftime. object defaults to (GET-UNIVERSAL-TIME).

(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

(POSIX:MAKE-XTERM-IO-STREAM &KEY title)

When running under the X Window System, you can create a bidirectional STREAM, which uses a new dedicated xterm, 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.

(POSIX:FFS n)

Find the first bit set. Like ffs, but implemented in Lisp and supports BIGNUMs.

Prev	Up	Next
32.10. Advanced Readline and History Functionality	Home	32.12. Oracle Interface