.. default-domain:: chpl .. module:: POSIX :synopsis: The ``OS.POSIX`` module provides definitions matching the POSIX POSIX ===== **Usage** .. code-block:: chapel use OS.POSIX; or .. code-block:: chapel import OS.POSIX; The ``OS.POSIX`` module provides definitions matching the POSIX programming interface, specifically POSIX.1-2017. That standard can be found at . 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:: type blkcnt_t Explicit conversions between ``blkcnt_t`` and ``c_int`` are also defined, to support usability. .. type:: type blksize_t Explicit conversions between ``blksize_t`` and ``c_int`` are also defined, to support usability. .. type:: type dev_t Explicit conversions between ``dev_t`` and ``c_int`` are also defined, to support usability. .. type:: type gid_t Explicit conversions between ``gid_t`` and ``c_int`` are also defined, to support usability. .. type:: type ino_t Explicit conversions between ``ino_t`` and ``c_uint`` are also defined, to support usability. .. type:: 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:: type nlink_t Explicit conversions between ``nlink_t`` and ``c_int`` are also defined, to support usability. .. type:: type off_t Explicit conversions between ``off_t`` and ``c_int`` and ``off_t`` and integral types are also defined, to support usability. .. type:: type suseconds_t Explicit conversions between ``suseconds_t`` and ``c_int`` are also defined, to support usability. .. type:: type time_t Explicit conversions between ``time_t`` and ``c_int`` are also defined, to support usability. .. type:: 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``. .. attribute:: var tv_sec: time_t Seconds since the epoch, Jan. 1, 1970 .. attribute:: var tv_nsec: c_long Nanoseconds .. data:: 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. .. data:: 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) .. data:: const EADDRINUSE: c_int Address already in use. Only one usage of each address is normally permitted. .. data:: 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. .. data:: 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. .. data:: const EAGAIN: c_int Resource temporarily unavailable. This is a temporary condition and later calls to the same routine may complete normally. .. data:: const EALREADY: c_int Operation already in progress. An operation was attempted on a non-blocking object that already had an operation in progress. .. data:: 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). .. data:: const EBADMSG: c_int Bad message. A corrupted message was detected. (POSIX.1) .. data:: 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. .. data:: const ECANCELED: c_int Operation canceled. The scheduled operation was canceled. (POSIX.1) .. data:: 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) .. data:: const ECONNABORTED: c_int Software caused connection abort. A connection abort was caused internal to your host machine. .. data:: 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. .. data:: 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. .. data:: 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) .. data:: const EDESTADDRREQ: c_int Destination address required. A required address was omitted from an operation on a socket. .. data:: const EDOM: c_int Numerical argument out of domain. A numerical input argument was outside the defined domain of the mathematical function. .. data:: 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. .. data:: 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. .. data:: const EFAULT: c_int Bad address. The system detected an invalid address in attempting to use an argument of a call. .. data:: const EFBIG: c_int File too large. The size of a file exceeded the maximum. .. data:: const EHOSTUNREACH: c_int No route to host. A socket operation was attempted to an unreachable host. .. data:: const EIDRM: c_int Identifier removed. An IPC identifier was removed while the current process was waiting on it. .. data:: 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. .. data:: 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. .. data:: 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. .. data:: 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). .. data:: 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. .. data:: 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. .. data:: const EISDIR: c_int Is a directory. An attempt was made to open a directory with write mode specified. .. data:: const ELOOP: c_int Too many levels of symbolic links. A path name lookup involved more than 32 (MAXSYMLINKS) symbolic links. .. data:: 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. .. data:: const EMLINK: c_int Too many links. Maximum allowable hard links to a single file has been exceeded. .. data:: 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. .. data:: const EMULTIHOP: c_int Multihop attempted. .. data:: 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. .. data:: const ENETDOWN: c_int Network is down. A socket operation encountered a dead network. .. data:: const ENETRESET: c_int Network dropped connection on reset. The host you were connected to crashed and rebooted. .. data:: const ENETUNREACH: c_int Network is unreachable. A socket operation was attempted to an unreachable network. .. data:: 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. .. data:: 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. .. data:: 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. .. data:: 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. .. data:: 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. .. data:: const ENOLCK: c_int No locks available. A system-imposed limit on the number of simultaneous file locks was reached. .. data:: const ENOLINK: c_int Link has been severed. .. data:: 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. .. data:: 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. .. data:: const ENOPROTOOPT: c_int Protocol not available. A bad option or level was specified in a getsockopt or setsockopt system call. .. data:: 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. .. data:: const ENOSYS: c_int Function not implemented. Attempted a system call that is not available on this system. .. data:: 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. .. data:: 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. .. data:: const ENOTEMPTY: c_int Directory not empty. A directory with entries other than '.' and '..' was supplied to a remove directory or rename call. .. data:: const ENOTRECOVERABLE: c_int State not recoverable. .. data:: const ENOTSOCK: c_int Socket operation on non-socket. .. data:: 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. .. data:: 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. .. data:: 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. .. data:: 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. .. data:: 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. .. data:: const EOWNERDEAD: c_int Owner died. .. data:: 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. .. data:: const EPIPE: c_int Broken pipe. A write on a pipe, socket or FIFO for which there is no process to read the data. .. data:: const EPROTO: c_int Protocol error. A device or socket encountered an unrecoverable protocol error. .. data:: const EPROTONOSUPPORT: c_int Protocol not supported. The protocol has not been configured into the system or no implementation for it exists. .. data:: 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. .. data:: 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). .. data:: 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. .. data:: const ESPIPE: c_int Illegal seek. An lseek system call was issued on a socket, pipe or FIFO. .. data:: const ESRCH: c_int No such process. No process could be found corresponding to that specified by the given process ID. .. data:: 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. .. data:: 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). .. data:: 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. .. data:: const EWOULDBLOCK: c_int Operation would block (may be same value as EAGAIN). .. data:: const EXDEV: c_int Cross-device link. A hard link to a file on another file system was attempted. .. function:: 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. .. data:: const SIGABRT: c_int Abort Signal (from abort(3)) .. data:: const SIGALRM: c_int Timer Signal (from alarm(2)) .. data:: const SIGBUS: c_int Bus error (bad memory access) .. data:: const SIGCHLD: c_int Child stopped or terminated .. data:: const SIGCONT: c_int Continue if stopped .. data:: const SIGFPE: c_int Floating-point exception .. data:: const SIGHUP: c_int Hangup detected on controlling terminal or death of controlling process .. data:: const SIGILL: c_int Illegal Instruction .. data:: const SIGINT: c_int Interrupt from keyboard .. data:: const SIGKILL: c_int Kill signal .. data:: const SIGPIPE: c_int Broken pipe: write to pipe with no readers .. data:: const SIGQUIT: c_int Quit from keyboard .. data:: const SIGSEGV: c_int Invalid memory reference .. data:: const SIGSTOP: c_int Stop process .. data:: const SIGTERM: c_int Termination signal .. data:: const SIGTRAP: c_int Trace/breakpoint trap .. data:: const SIGTSTP: c_int Stop typed at terminal .. data:: const SIGTTIN: c_int Terminal input for background process .. data:: const SIGTTOU: c_int Terminal output for background process .. data:: const SIGURG: c_int Urgent condition on socket .. data:: const SIGUSR1: c_int User-defined signal 1 .. data:: const SIGUSR2: c_int User-defined signal 2 .. data:: const SIGXCPU: c_int CPU time limit exceeded .. data:: const SIGXFSZ: c_int File size limit exceeded .. data:: const O_ACCMODE: c_int Mask for file access modes. .. data:: const O_APPEND: c_int Set append mode. .. data:: const O_CLOEXEC: c_int Sets the ``FD_CLOEXEC`` flag of new descriptor to close it after execution of an ``exec`` function. .. data:: const O_CREAT: c_int Create file if it does not exist. .. data:: const O_DIRECTORY: c_int Fail if file is a non-directory file. .. data:: const O_DSYNC: c_int Write according to synchronized I/O data integrity completion. .. data:: const O_EXCL: c_int Exclusive use flag. .. data:: const O_NOCTTY: c_int Do not assign controlling terminal. .. data:: const O_NOFOLLOW: c_int Do not follow symbolic links. .. data:: const O_NONBLOCK: c_int Non-blocking mode. .. data:: const O_RDONLY: c_int Open for reading only. .. data:: const O_RDWR: c_int Open for reading and writing .. data:: const O_SYNC: c_int Write according to synchronized I/O file integrity completion. .. data:: const O_TRUNC: c_int Truncate flag. .. data:: const O_WRONLY: c_int Open for writing only. .. function:: proc creat(path: c_ptrConst(c_char), mode: mode_t = 0): c_int Create a new file or rewrite an existing file. .. function:: proc open(path: c_ptrConst(c_char), oflag: c_int, mode: mode_t = 0: mode_t): c_int Open a file. .. function:: proc getenv(name: c_ptrConst(c_char)): c_ptr(c_char) Get the value of an environment variable. .. function:: proc strerror(errnum: c_int): c_ptrConst(c_char) Get the error message string for ``errnum`` .. function:: proc strlen(s: c_ptrConst(c_char)): c_size_t Get the length of the null-terminated string. .. data:: const FD_SETSIZE: c_int Maximum number of file descriptors that :type:`fd_set` can hold. .. record:: fd_set Contains a fixed amount of file descriptors. .. function:: proc FD_CLR(fd: c_int, fdset: c_ptr(fd_set)) Clears the bit for the file descriptor ``fd`` in ``fdset``. .. function:: 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``. .. function:: proc FD_SET(fd: c_int, fdset: c_ptr(fd_set)) Sets the bit for the file descriptor ``fd`` in ``fdset``. .. function:: proc FD_ZERO(fdset: c_ptr(fd_set)) Initializes all file descriptors in ``fdset`` to zero. .. function:: 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``. .. function:: proc S_IRWXU: mode_t Shorthand for (:proc:`S_IRUSR` | :proc:`S_IWUSR` | :proc:`S_IXUSR`). .. function:: proc S_IRUSR: mode_t Read permission bit for the file's owner. .. function:: proc S_IWUSR: mode_t Write permission bit for the file's owner. .. function:: proc S_IXUSR: mode_t Execute permission bit for the file's owner. .. function:: proc S_IRWXG: mode_t Shorthand for (:proc:`S_IRGRP` | :proc:`S_IWGRP` | :proc:`S_IXGRP`). .. function:: proc S_IRGRP: mode_t Read permission bit for the file's group. .. function:: proc S_IWGRP: mode_t Write permission bit for the file's group. .. function:: proc S_IXGRP: mode_t Execute permission bit for the file's group. .. function:: proc S_IRWXO: mode_t Shorthand for (:proc:`S_IROTH` | :proc:`S_IWOTH` | :proc:`S_IXOTH`). .. function:: proc S_IROTH: mode_t Read permission bit for others. .. function:: proc S_IWOTH: mode_t Write permission bit for others. .. function:: proc S_IXOTH: mode_t Execute permission bit for others. .. function:: proc S_ISUID: mode_t Set user ID on execute bit. .. function:: proc S_ISGID: mode_t Set group ID on execute bit. .. function:: 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 :proc:`stat`. .. attribute:: var st_dev: dev_t Device. .. attribute:: var st_ino: ino_t File serial number. .. attribute:: var st_mode: mode_t File mode. .. attribute:: var st_nlink: nlink_t Link count. .. attribute:: var st_uid: uid_t User ID of the file's owner. .. attribute:: var st_gid: gid_t Group ID of the file's group. .. attribute:: var st_rdev: dev_t Device number, if device. .. attribute:: var st_size: off_t Size of file, in bytes. .. attribute:: var st_atim: struct_timespec Last data access timestamp. .. attribute:: var st_mtim: struct_timespec Last data modification timestamp. .. attribute:: var st_ctim: struct_timespec Last file status change timestamp. .. attribute:: var st_blksize: blksize_t Optimal block size for I/O. .. attribute:: var st_blocks: blkcnt_t Number 512-byte blocks allocated. .. function:: proc chmod(path: c_ptrConst(c_char), mode: mode_t): c_int Changes the mode of a file. .. function:: proc stat(path: c_ptrConst(c_char), buf: c_ptr(struct_stat)): c_int Get the status of a file, should be used with :record:`struct_stat`. .. record:: struct_timeval The structure ``timeval`` from ``sys/time.h``. .. attribute:: var tv_sec: time_t Seconds since the epoch, Jan. 1, 1970 .. attribute:: var tv_usec: suseconds_t Nanoseconds .. record:: struct_timezone The structure ``timezone`` from ``time.h``. .. attribute:: var tz_minuteswest: c_int Minutes west of Greenwich .. attribute:: var tz_dsttime: c_int Type of DST correction .. function:: 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``. .. attribute:: var tm_sec: c_int Seconds [0,60] (60 allows for leap seconds) .. attribute:: var tm_min: c_int Minutes [0,59] .. attribute:: var tm_hour: c_int Hour [0,23] .. attribute:: var tm_mday: c_int Day of month [1,31] .. attribute:: var tm_mon: c_int Month of year [0,11] .. attribute:: var tm_year: c_int Years since 1900 .. attribute:: var tm_wday: c_int Day of week [0,6] (Sunday =0) .. attribute:: var tm_yday: c_int Day of year [0,365] .. attribute:: var tm_isdst: c_int Daylight Savings flag .. function:: proc asctime(timeptr: c_ptr(struct_tm)): c_ptr(c_char) Get the date and time as a string. .. function:: 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`` .. function:: proc localtime(timer: c_ptr(time_t)): c_ptr(struct_tm) Convert the time to a local time. .. function:: 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`` .. function:: proc time(tloc: c_ptr(time_t)): time_t Get the time. .. function:: proc close(fildes: c_int): c_int Close a file descriptor. .. function:: proc pipe(fildes: c_ptr(c_array(c_int, 2))): c_int Create a pipe. .. function:: 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``. .. function:: proc write(fildes: c_int, buf: c_ptr(void), size: c_size_t): c_ssize_t Write ``size`` bytes to file descriptor from ``buf``. .. function:: 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. :arg dest: the destination memory area to copy to :arg src: the source memory area to copy from :arg n: the number of bytes from src to copy to dest .. function:: 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 :proc:`memmove` if memory areas do overlap. This is a simple wrapper over the C ``memcpy()`` function. :arg dest: the destination memory area to copy to :arg src: the source memory area to copy from :arg n: the number of bytes from src to copy to dest .. function:: 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. .. function:: 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. :arg s: the destination memory area to fill :arg c: the byte value to use :arg n: the number of bytes of s to fill :returns: ``s``