33.1. System Calls
Prev | Chapter 33. Extensions Implemented as Modules | Next

## 33.1. System Calls

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 (`OPEN`ing 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: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`).

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

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

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

`(`POSIX:FFS` `n`)`: Find the first bit set. Like `ffs`, but implemented in Lisp and supports `BIGNUM`s.

### 33.1.6. Encryption

`(POSIX:CRYPT `key` `salt`)`
  Call `crypt`, arguments are `STRING`s.
`(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:GETPGID `pid`)`
`(`SETF` (POSIX:GETPGID `pid`) `pgid`)`
  Call `getpgid` and `setpgid`.
`(POSIX:SETREUID ruid euid)`
  Call `setreuid`.
`(POSIX:SETREGID rgid egid)`
  Call `setregid`.
`(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`.
`(POSIX:GETGROUPS)`
`(`SETF` (POSIX:GETGROUPS) `list`)`
  Call `getgroups` and `setgroups`.

### 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)`

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

### 33.1.11. XTerm

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

### 33.1.12. Standard file input and output

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

`(`fopen` `filename` `mode`)`
`(`fdopen` fd `mode`)`
`(`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:FCLOSE`, `OS:FFLUSH`, `OS:FILENO` may `SIGNAL`s an `ERROR`.

Return values

`OS:FOPEN`
`OS:FDOPEN`
  FFI:file = `FFI:FOREIGN-POINTER`
`OS:FCLOSE`
`OS:FFLUSH`
`OS:CLEARERR`
  no values
`OS:FEOF`
`OS:FERROR`
  `BOOLEAN`
`OS:FILENO`
  `INTEGER` (file descriptor)

### Note

These are 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.

These are only present if “FFI” is present.

| These notes document CLISP version 2.45 | Last modified: 2008-05-14

Enter your search termsSubmit search form
Webclisp.cons.orgclisp.podval.orgwww.lisp.org

Prev | Up | Next
Chapter 33. Extensions Implemented as Modules | Home | 33.2. Internationalization of User Programs