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

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

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

(POSIX:FILE-TREE-WALK pathname function &KEY FD-LIMIT CHDIR DEPTH MOUNT PHYS)

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:

   :F

   The object is a file.

   :D

   The object is a directory.

   :DP

   The object is a directory and subdirectories have been visited. (This condition shall only occur if the :DEPTH argument is non-NIL.)

   :SL

   The object is a symbolic link. (This condition shall only occur if the PHYS argument is non-NIL.)

   :SLN

   The object is a symbolic link that does not name an existing file. (This condition shall only occur if the PHYS argument is NIL.)

   :DNR

   The object is a directory that cannot be read. The fn function shall not be called for any of its descendants.

   :NS

   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

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.

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.

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

When preserve is non-NIL, try to duplicate the time, owner, and permission characteristics of each source file in the corresponding destination file, similar to cp -p.

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

The actual destination file created is (MERGE-PATHNAMES source destination) so that (POSIX:COPY-FILE "foo" "dir/") creates "dir/foo" and (POSIX:COPY-FILE "foo.csv" "bar") creates "bar.csv". If you want to actually copy "foo.csv" to "bar", do (POSIX:COPY-FILE (MAKE-PATHNAME :name "foo.csv") "bar").

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

(POSIX:MKDTEMP filename)

Calls mkdtemp; creates a new empty temporary directory and returns its namestring.

(POSIX:SYNC &OPTIONAL stream)

Calls fsync (FlushFileBuffers on Win32) on the file descriptor associated with stream, or sync when stream is not supplied

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

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

(POSIX:USAGE &OPTIONAL what)

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.

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

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

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

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

(POSIX:WITH-SUBPROCESSES &BODY)

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

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

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

• When object is a STRING, it is parsed into a universal time 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).

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

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)

(POSIX:ERRNO &OPTIONAL error-code)

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.

(OS:LAST-ERROR &OPTIONAL error-code)

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

Platform Dependent: Win32 platform only.

(POSIX:STRERROR &OPTIONAL error-code)

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

This calls strerror.

(OS:FORMAT-MESSAGE &OPTIONAL error-code)

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

Platform Dependent: Win32 platform only.

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