POSIX

Usage

use OS.POSIX;

or

import OS.POSIX;

The OS.POSIX module provides definitions matching the POSIX programming interface, specifically POSIX.1-2017. That standard can be found at <https://pubs.opengroup.org/onlinepubs/9699919799/>.

There is one unavoidable difference between POSIX and OS.POSIX. POSIX defines a function named select(), which OS.POSIX could not use because select is itself a Chapel keyword.

type blkcnt_t

Explicit conversions between blkcnt_t and c_int are also defined, to support usability.

type blksize_t

Explicit conversions between blksize_t and c_int are also defined, to support usability.

type dev_t

Explicit conversions between dev_t and c_int are also defined, to support usability.

type gid_t

Explicit conversions between gid_t and c_int are also defined, to support usability.

type ino_t

Explicit conversions between ino_t and c_uint are also defined, to support usability.

type mode_t

Bitwise-AND and bitwise-OR operators are defined on mode_t operands, to support querying and constructing mode values. Explicit conversions between mode_t and c_int are also defined, to support usability.

type nlink_t

Explicit conversions between nlink_t and c_int are also defined, to support usability.

type off_t

Explicit conversions between off_t and c_int and off_t and integral types are also defined, to support usability.

type suseconds_t

Explicit conversions between suseconds_t and c_int are also defined, to support usability.

type time_t

Explicit conversions between time_t and c_int are also defined, to support usability.

type uid_t

Explicit conversions between uid_t and c_int are also defined, to support usability.

record struct_timespec

The structure timespec from time.h.

var tv_sec: time_t

Seconds since the epoch, Jan. 1, 1970

var tv_nsec: c_long

Nanoseconds

const E2BIG: c_int

Argument list too long. The number of bytes used for the argument and environment list of the new process exceeded the current limit.

const EACCES: c_int

Permission denied. An attempt was made to access a file in a way forbidden by its file access permissions. (POSIX.1)

const EADDRINUSE: c_int

Address already in use. Only one usage of each address is normally permitted.

const EADDRNOTAVAIL: c_int

Can’t assign requested address. Normally results from an attempt to create a socket with an address not on this machine.

const EAFNOSUPPORT: c_int

Address family not supported by protocol family. An address incompatible with the requested protocol was used. For example, you should not necessarily expect to be able to use NS addresses with ARPA Internet protocols.

const EAGAIN: c_int

Resource temporarily unavailable. This is a temporary condition and later calls to the same routine may complete normally.

const EALREADY: c_int

Operation already in progress. An operation was attempted on a non-blocking object that already had an operation in progress.

const EBADF: c_int

Bad file descriptor. A file descriptor argument was out of range, referred to no open file, or a read (write) request was made to a file that was only open for writing (reading).

const EBADMSG: c_int

Bad message. A corrupted message was detected. (POSIX.1)

const EBUSY: c_int

Device or resource busy. An attempt to use a system resource which was in use at the time in a manner which would have conflicted with the request.

const ECANCELED: c_int

Operation canceled. The scheduled operation was canceled. (POSIX.1)

const ECHILD: c_int

No child processes. A wait or waitpid system call was executed by a process that had no existing or unwaited-for child processes. (POSIX.1)

const ECONNABORTED: c_int

Software caused connection abort. A connection abort was caused internal to your host machine.

const ECONNREFUSED: c_int

Connection refused. No connection could be made because the target machine actively refused it. This usually results from trying to connect to a service that is inactive on the foreign host.

const ECONNRESET: c_int

Connection reset by peer. A connection was forcibly closed by a peer. This normally results from a loss of the connection on the remote socket due to a timeout or a reboot.

const EDEADLK: c_int

Resource deadlock avoided. An attempt was made to lock a system resource that would have resulted in a deadlock situation. (POSIX.1)

const EDESTADDRREQ: c_int

Destination address required. A required address was omitted from an operation on a socket.

const EDOM: c_int

Numerical argument out of domain. A numerical input argument was outside the defined domain of the mathematical function.

const EDQUOT: c_int

Disc quota exceeded. A write system call to an ordinary file, the creation of a directory or symbolic link, or the creation of a directory entry failed because the user’s quota of disk blocks was exhausted, or the allocation of an inode for a newly created file failed because the user’s quota of inodes was exhausted.

const EEXIST: c_int

File exists. An existing file was mentioned in an inappropriate context, for instance, as the new link name in a link system call.

const EFAULT: c_int

Bad address. The system detected an invalid address in attempting to use an argument of a call.

const EFBIG: c_int

File too large. The size of a file exceeded the maximum.

const EHOSTUNREACH: c_int

No route to host. A socket operation was attempted to an unreachable host.

const EIDRM: c_int

Identifier removed. An IPC identifier was removed while the current process was waiting on it.

const EILSEQ: c_int

Illegal byte sequence. While decoding a multibyte character the function came along an invalid or an incomplete sequence of bytes or the given wide character is invalid.

This error might be returned for example in the case of an illegal UTF-8 byte sequence.

const EINPROGRESS: c_int

Operation now in progress. An operation that takes a long time to complete (such as a connect system call) was attempted on a non-blocking object.

const EINTR: c_int

Interrupted system call. An asynchronous signal (such as SIGINT or SIGQUIT) was caught by the process during the execution of an interruptible function. If the signal handler performs a normal return, the interrupted system call will seem to have returned the error condition.

const EINVAL: c_int

Invalid argument. Some invalid argument was supplied. (For example, specifying an undefined signal to a signal system call or a kill system call).

const EIO: c_int

Input/output error. Some physical input or output error occurred. This error will not be reported until a subsequent operation on the same file descriptor and may be lost (over written) by any subsequent errors.

const EISCONN: c_int

Socket is already connected. A connect system call was made on an already connected socket; or, a sendto or sendmsg system call on a connected socket specified a destination when already connected.

const EISDIR: c_int

Is a directory. An attempt was made to open a directory with write mode specified.

const ELOOP: c_int

Too many levels of symbolic links. A path name lookup involved more than 32 (MAXSYMLINKS) symbolic links.

const EMFILE: c_int

Too many open files. Maximum number of file descriptors allowable in the process has been reached and requests for an open cannot be satisfied until at least one has been closed. The getdtablesize system call will obtain the current limit.

const EMLINK: c_int

Too many links. Maximum allowable hard links to a single file has been exceeded.

const EMSGSIZE: c_int

Message too long. A message sent on a socket was larger than the internal message buffer or some other network limit.

const EMULTIHOP: c_int

Multihop attempted.

const ENAMETOOLONG: c_int

File name too long. A component of a path name exceeded {NAME_MAX} characters, or an entire path name exceeded {PATH_MAX} characters.

const ENETDOWN: c_int

Network is down. A socket operation encountered a dead network.

const ENETRESET: c_int

Network dropped connection on reset. The host you were connected to crashed and rebooted.

const ENETUNREACH: c_int

Network is unreachable. A socket operation was attempted to an unreachable network.

const ENFILE: c_int

Too many open files in system. Maximum number of open files allowable on the system has been reached and requests for an open cannot be satisfied until at least one has been closed.

const ENOBUFS: c_int

No buffer space available. An operation on a socket or pipe was not performed because the system lacked sufficient buffer space or because a queue was full.

const ENODEV: c_int

Operation not supported by device. An attempt was made to apply an inappropriate function to a device, for example, trying to read a write-only device such as a printer.

const ENOENT: c_int

No such file or directory. A component of a specified pathname did not exist, or the pathname was an empty string.

const ENOEXEC: c_int

Exec format error. A request was made to execute a file that, although it has the appropriate permissions, was not in the format required for an executable file.

const ENOLCK: c_int

No locks available. A system-imposed limit on the number of simultaneous file locks was reached.

const ENOLINK: c_int

Link has been severed.

const ENOMEM: c_int

Cannot allocate memory. The new process image required more memory than was allowed by the hardware or by system-imposed memory management constraints. A lack of swap space is normally temporary; however, a lack of core is not. Soft limits may be increased to their corresponding hard limits.

const ENOMSG: c_int

No message of desired type. An IPC message queue does not contain a message of the desired type, or a message catalog does not contain the requested message.

const ENOPROTOOPT: c_int

Protocol not available. A bad option or level was specified in a getsockopt or setsockopt system call.

const ENOSPC: c_int

No space left on device. A write system call to an ordinary file, the creation of a directory or symbolic link, or the creation of a directory entry failed because no more disk blocks were available on the file system, or the allocation of an inode for a newly created file failed because no more inodes were available on the file system.

const ENOSYS: c_int

Function not implemented. Attempted a system call that is not available on this system.

const ENOTCONN: c_int

Socket is not connected. An request to send or receive data was disallowed because the socket was not connected and (when sending on a datagram socket) no address was supplied.

const ENOTDIR: c_int

Not a directory. A component of the specified pathname existed, but it was not a directory, when a directory was expected.

const ENOTEMPTY: c_int

Directory not empty. A directory with entries other than ‘.’ and ‘..’ was supplied to a remove directory or rename call.

const ENOTRECOVERABLE: c_int

State not recoverable.

const ENOTSOCK: c_int

Socket operation on non-socket.

const ENOTSUP: c_int

Operation not supported. The attempted operation is not supported for the type of object referenced. Usually this occurs when a file descriptor refers to a file or socket that cannot support this operation, for example, trying to accept a connection on a datagram socket.

const ENOTTY: c_int

Inappropriate ioctl for device. A control function (e.g. ioctl system call) was attempted for a file or special device for which the operation was inappropriate.

const ENXIO: c_int

Device not configured. Input or output on a special file referred to a device that did not exist, or made a request beyond the limits of the device. This error may also occur when, for example, a tape drive is not online or no disk pack is loaded on a drive.

const EOPNOTSUPP: c_int

Operation not supported. The attempted operation is not supported for the type of object referenced. Usually this occurs when a file descriptor refers to a file or socket that cannot support this operation, for example, trying to accept a connection on a datagram socket.

const EOVERFLOW: c_int

Value too large to be stored in data type. A numerical result of the function was too large to be stored in the caller provided space.

const EOWNERDEAD: c_int

Owner died.

const EPERM: c_int

Operation not permitted. An attempt was made to perform an operation limited to processes with appropriate privileges or to the owner of a file or other resources.

const EPIPE: c_int

Broken pipe. A write on a pipe, socket or FIFO for which there is no process to read the data.

const EPROTO: c_int

Protocol error. A device or socket encountered an unrecoverable protocol error.

const EPROTONOSUPPORT: c_int

Protocol not supported. The protocol has not been configured into the system or no implementation for it exists.

const EPROTOTYPE: c_int

Protocol wrong type for socket. A protocol was specified that does not support the semantics of the socket type requested. For example, you cannot use the ARPA Internet UDP protocol with type SOCK_STREAM.

const ERANGE: c_int

Result too large. A numerical result of the function was too large to fit in the available space (perhaps exceeded precision).

const EROFS: c_int

Read-only file system. An attempt was made to modify a file or directory on a file system that was read-only at the time.

const ESPIPE: c_int

Illegal seek. An lseek system call was issued on a socket, pipe or FIFO.

const ESRCH: c_int

No such process. No process could be found corresponding to that specified by the given process ID.

const ESTALE: c_int

Stale NFS file handle. An attempt was made to access an open file (on an NFS file system) which is now unavailable as referenced by the file descriptor. This may indicate the file was deleted on the NFS server or some other catastrophic event occurred.

const ETIMEDOUT: c_int

Operation timed out. A connect or send system call failed because the connected party did not properly respond after a period of time (The timeout period is dependent on the communication protocol).

const ETXTBSY: c_int

Text file busy. The new process was a pure procedure (shared text) file which was open for writing by another process, or while the pure procedure file was being executed an open system call requested write access.

const EWOULDBLOCK: c_int

Operation would block (may be same value as EAGAIN).

const EXDEV: c_int

Cross-device link. A hard link to a file on another file system was attempted.

proc errno: c_int

POSIX says that errno is a “modifiable lvalue of type int”, but for now we only support reading from it, not assigning to it.

const SIGABRT: c_int

Abort Signal (from abort(3))

const SIGALRM: c_int

Timer Signal (from alarm(2))

const SIGBUS: c_int

Bus error (bad memory access)

const SIGCHLD: c_int

Child stopped or terminated

const SIGCONT: c_int

Continue if stopped

const SIGFPE: c_int

Floating-point exception

const SIGHUP: c_int

Hangup detected on controlling terminal or death of controlling process

const SIGILL: c_int

Illegal Instruction

const SIGINT: c_int

Interrupt from keyboard

const SIGKILL: c_int

Kill signal

const SIGPIPE: c_int

Broken pipe: write to pipe with no readers

const SIGQUIT: c_int

Quit from keyboard

const SIGSEGV: c_int

Invalid memory reference

const SIGSTOP: c_int

Stop process

const SIGTERM: c_int

Termination signal

const SIGTRAP: c_int

Trace/breakpoint trap

const SIGTSTP: c_int

Stop typed at terminal

const SIGTTIN: c_int

Terminal input for background process

const SIGTTOU: c_int

Terminal output for background process

const SIGURG: c_int

Urgent condition on socket

const SIGUSR1: c_int

User-defined signal 1

const SIGUSR2: c_int

User-defined signal 2

const SIGXCPU: c_int

CPU time limit exceeded

const SIGXFSZ: c_int

File size limit exceeded

const O_ACCMODE: c_int

Mask for file access modes.

const O_APPEND: c_int

Set append mode.

const O_CLOEXEC: c_int

Sets the FD_CLOEXEC flag of new descriptor to close it after execution of an exec function.

const O_CREAT: c_int

Create file if it does not exist.

const O_DIRECTORY: c_int

Fail if file is a non-directory file.

const O_DSYNC: c_int

Write according to synchronized I/O data integrity completion.

const O_EXCL: c_int

Exclusive use flag.

const O_NOCTTY: c_int

Do not assign controlling terminal.

const O_NOFOLLOW: c_int

Do not follow symbolic links.

const O_NONBLOCK: c_int

Non-blocking mode.

const O_RDONLY: c_int

Open for reading only.

const O_RDWR: c_int

Open for reading and writing

const O_SYNC: c_int

Write according to synchronized I/O file integrity completion.

const O_TRUNC: c_int

Truncate flag.

const O_WRONLY: c_int

Open for writing only.

proc creat(path: c_ptrConst(c_char), mode: mode_t = 0): c_int

Create a new file or rewrite an existing file.

proc open(path: c_ptrConst(c_char), oflag: c_int, mode: mode_t = 0: mode_t): c_int

Open a file.

proc getenv(name: c_ptrConst(c_char)): c_ptr(c_char)

Get the value of an environment variable.

proc strerror(errnum: c_int): c_ptrConst(c_char)

Get the error message string for errnum

proc strlen(s: c_ptrConst(c_char)): c_size_t

Get the length of the null-terminated string.

const FD_SETSIZE: c_int

Maximum number of file descriptors that fd_set can hold.

record fd_set

Contains a fixed amount of file descriptors.

proc FD_CLR(fd: c_int, fdset: c_ptr(fd_set))

Clears the bit for the file descriptor fd in fdset.

proc FD_ISSET(fd: c_int, fdset: c_ptr(fd_set)): c_int

Checks if the bit for the file descriptor fd is set in fdset.

proc FD_SET(fd: c_int, fdset: c_ptr(fd_set))

Sets the bit for the file descriptor fd in fdset.

proc FD_ZERO(fdset: c_ptr(fd_set))

Initializes all file descriptors in fdset to zero.

proc select_posix(nfds: c_int, readfds: c_ptr(fd_set), writefds: c_ptr(fd_set), errorfds: c_ptr(fd_set), timeout: c_ptr(struct_timeval)): c_int

Indicates which of the specified file descriptors is ready for reading or writing, or has an error condition pending. If no file descriptors are ready, the procedure blocks until the timeout.

proc S_IRWXU: mode_t

Shorthand for (S_IRUSR | S_IWUSR | S_IXUSR).

proc S_IRUSR: mode_t

Read permission bit for the file’s owner.

proc S_IWUSR: mode_t

Write permission bit for the file’s owner.

proc S_IXUSR: mode_t

Execute permission bit for the file’s owner.

proc S_IRWXG: mode_t

Shorthand for (S_IRGRP | S_IWGRP | S_IXGRP).

proc S_IRGRP: mode_t

Read permission bit for the file’s group.

proc S_IWGRP: mode_t

Write permission bit for the file’s group.

proc S_IXGRP: mode_t

Execute permission bit for the file’s group.

proc S_IRWXO: mode_t

Shorthand for (S_IROTH | S_IWOTH | S_IXOTH).

proc S_IROTH: mode_t

Read permission bit for others.

proc S_IWOTH: mode_t

Write permission bit for others.

proc S_IXOTH: mode_t

Execute permission bit for others.

proc S_ISUID: mode_t

Set user ID on execute bit.

proc S_ISGID: mode_t

Set group ID on execute bit.

proc S_ISVTX: mode_t

Sticky bit

record struct_stat

A Chapel version of the POSIX structure stat, which contains common fields. This should be used with stat.

var st_dev: dev_t

Device.

var st_ino: ino_t

File serial number.

var st_mode: mode_t

File mode.

var st_nlink: nlink_t

Link count.

var st_uid: uid_t

User ID of the file’s owner.

var st_gid: gid_t

Group ID of the file’s group.

var st_rdev: dev_t

Device number, if device.

var st_size: off_t

Size of file, in bytes.

var st_atim: struct_timespec

Last data access timestamp.

var st_mtim: struct_timespec

Last data modification timestamp.

var st_ctim: struct_timespec

Last file status change timestamp.

var st_blksize: blksize_t

Optimal block size for I/O.

var st_blocks: blkcnt_t

Number 512-byte blocks allocated.

proc chmod(path: c_ptrConst(c_char), mode: mode_t): c_int

Changes the mode of a file.

proc stat(path: c_ptrConst(c_char), buf: c_ptr(struct_stat)): c_int

Get the status of a file, should be used with struct_stat.

record struct_timeval

The structure timeval from sys/time.h.

var tv_sec: time_t

Seconds since the epoch, Jan. 1, 1970

var tv_usec: suseconds_t

Nanoseconds

record struct_timezone

The structure timezone from time.h.

var tz_minuteswest: c_int

Minutes west of Greenwich

var tz_dsttime: c_int

Type of DST correction

proc gettimeofday(tp: c_ptr(struct_timeval), tzp: c_ptr(struct_timezone)): c_int

Get the date and time, based on the timezone in tzp. The result is stored in tp.

record struct_tm

The structure tm from time.h.

var tm_sec: c_int

Seconds [0,60] (60 allows for leap seconds)

var tm_min: c_int

Minutes [0,59]

var tm_hour: c_int

Hour [0,23]

var tm_mday: c_int

Day of month [1,31]

var tm_mon: c_int

Month of year [0,11]

var tm_year: c_int

Years since 1900

var tm_wday: c_int

Day of week [0,6] (Sunday =0)

var tm_yday: c_int

Day of year [0,365]

var tm_isdst: c_int

Daylight Savings flag

proc asctime(timeptr: c_ptr(struct_tm)): c_ptr(c_char)

Get the date and time as a string.

proc asctime_r(timeptr: c_ptr(struct_tm), buf: c_ptr(c_char)): c_ptr(c_char)

Get the date and time as a string, using the given buffer.

Returns

buf

proc localtime(timer: c_ptr(time_t)): c_ptr(struct_tm)

Convert the time to a local time.

proc localtime_r(timer: c_ptr(time_t), result: c_ptr(struct_tm)): c_ptr(struct_tm)

Convert the time to a local time, storing the result in the given struct.

Returns

result

proc time(tloc: c_ptr(time_t)): time_t

Get the time.

proc close(fildes: c_int): c_int

Close a file descriptor.

proc pipe(fildes: c_ptr(c_array(c_int, 2))): c_int

Create a pipe.

proc read(fildes: c_int, buf: c_ptr(void), size: c_size_t): c_ssize_t

Read size bytes from a file descriptor into buf.

proc write(fildes: c_int, buf: c_ptr(void), size: c_size_t): c_ssize_t

Write size bytes to file descriptor from buf.

proc memmove(dest: c_ptr(void), const src: c_ptr(void), n: c_size_t)

Copies n potentially overlapping bytes from memory area src to memory area dest.

This is a simple wrapper over the C memmove() function.

Arguments

• dest – the destination memory area to copy to

• src – the source memory area to copy from

• n – the number of bytes from src to copy to dest

proc memcpy(dest: c_ptr(void), const src: c_ptr(void), n: c_size_t)

Copies n non-overlapping bytes from memory area src to memory area dest. Use memmove if memory areas do overlap.

This is a simple wrapper over the C memcpy() function.

Arguments

• dest – the destination memory area to copy to

• src – the source memory area to copy from

• n – the number of bytes from src to copy to dest

proc memcmp(const s1: c_ptr(void), const s2: c_ptr(void), n: c_size_t): int

Compares the first n bytes of memory areas s1 and s2

This is a simple wrapper over the C memcmp() function.

Returns

returns an integer less than, equal to, or greater than zero if the first n bytes of s1 are found, respectively, to be less than, to match, or be greater than the first n bytes of s2.

proc memset(s: c_ptr(void), c: integral, n: c_size_t)

Fill bytes of memory with a particular byte value.

This is a simple wrapper over the C memset() function.

Arguments

• s – the destination memory area to fill

• c – the byte value to use

• n – the number of bytes of s to fill

Returns

s