.. include:: ../global.rst .. idio:currentmodule:: libc libc functions -------------- .. _`libc/access`: .. idio:function:: libc/access pathname mode in C, :samp:`access ({pathname}, {mode})` a wrapper to libc :manpage:`access(2)` :param pathname: file name :type pathname: string :param mode: accessibility check(s) :type mode: C/int :return: ``#t`` or ``#f`` :rtype: boolean :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL Any non-zero value from :manpage:`access(2)` returns ``#f``, no ^system-error is raised. .. warning:: Use of this function is discouraged. .. _`libc/asctime`: .. idio:function:: libc/asctime tm in C, :samp:`asctime ({tm})` a wrapper to libc :manpage:`asctime(3)` :param tm: :ref:`struct-tm ` :type tm: C/pointer :return: string representation of `tm` :rtype: string :raises ^system-error: .. _`libc/chdir`: .. idio:function:: libc/chdir path in C, :samp:`chdir ({path})` a wrapper to libc :manpage:`chdir(2)` :param path: directory name :type path: string :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `path` contains an ASCII NUL :raises ^system-error: .. _`libc/chmod`: .. idio:function:: libc/chmod pathname mode in C: :samp:`chmod ({pathname}, {mode})` a wrapper to libc :manpage:`chmod(2)` :param pathname: pathname :type pathname: string :param mode: mode flags :type mode: libc/mode_t :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: .. _`libc/chown`: .. idio:function:: libc/chown pathname owner group in C: :samp:`chown ({pathname}, {owner}, {group})` a wrapper to libc :manpage:`chown(2)` :param pathname: pathname :type pathname: string :param owner: User ID :type owner: libc/uid_t :param group: Group ID :type group: libc/gid_t :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: .. _`libc/chroot`: .. idio:function:: libc/chroot path in C: :samp:`chroot ({path})` a wrapper to libc :manpage:`chroot(2)` :param path: path :type path: string :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `path` contains an ASCII NUL :raises ^system-error: .. _`libc/close`: .. idio:function:: libc/close fd in C, :samp:`close ({fd})` a wrapper to libc :manpage:`close(2)` :param fd: file descriptor :type fd: C/int :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/close-if-open`: .. idio:function:: libc/close-if-open fd in C, :samp:`fcntl({fd}, F_GETFD) && close ({fd})` This exists to avoid :ref:`close ` reacting to ``EBADF`` which is handled specially. :param fd: file descriptor :type fd: C/int :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/ctermid`: .. idio:function:: libc/ctermid in C: :samp:`ctermid (s)` a wrapper to libc :manpage:`ctermid(3)` :return: controlling terminal pathname :rtype: pathname .. _`libc/ctime`: .. idio:function:: libc/ctime [t] in C, :samp:`ctime ({t})` a wrapper to libc :manpage:`ctime(3)` :param t: time in seconds since epoch, defaults to the result of :manpage:`time(2)` :type t: libc/time_t, optional :return: string representation of `t` :rtype: string :raises ^system-error: .. _`libc/dup`: .. idio:function:: libc/dup oldfd in C, :samp:`dup ({oldfd})` a wrapper to libc :manpage:`dup(2)` :param oldfd: file descriptor :type oldfd: C/int :return: new fd :rtype: C/int :raises ^system-error: .. _`libc/dup2`: .. idio:function:: libc/dup2 oldfd newfd in C, :samp:`dup2 ({oldfd}, {newfd})` a wrapper to libc :manpage:`dup2(2)` :param oldfd: file descriptor :type oldfd: C/int :param newfd: file descriptor :type newfd: fixnum or C/int :return: new fd :rtype: C/int :raises ^system-error: .. _`libc/exit`: .. idio:function:: libc/exit status in C, :samp:`exit ({status})` a wrapper to libc :manpage:`exit(3)` :param status: exit status :type status: fixnum or C/int **DOES NOT RETURN** :) .. _`libc/faccessat`: .. idio:function:: libc/faccessat dirfd pathname mode [flag ...] in C: :samp:`faccessat ({dirfd}, {pathname}, {mode}, {flags})` a wrapper to libc :manpage:`faccessat(2)` :param dirfd: file descriptor for a directory :type dirfd: C/int :param pathname: pathname :type pathname: string :param mode: accessibility check(s) :type mode: C/int :param flags: see below, default none :type flags: C/int, optional :return: ``#t`` or ``#f`` :rtype: boolean :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL Any non-zero value from :manpage:`faccessat(2)` returns ``#f``, no ^system-error is raised. The following value can be used for `dirfd`: ``AT_FDCWD`` The following values are defined for `flags`, they can be ``C/|``-bitwise OR'd together or passed as extra arguments: ``AT_EACCESS`` ``AT_SYMLINK_NOFOLLOW`` .. warning:: Use of this function is discouraged. .. note:: ``faccessat`` is not available on all systems. Use the ``IDIO_NO_FACCESSAT`` feature in :ref:`cond-expand `. .. _`libc/fchdir`: .. idio:function:: libc/fchdir fd in C: :samp:`fchdir ({fd})` a wrapper to libc :manpage:`fchdir(2)` :param fd: file descriptor :type fd: C/int :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/fchmod`: .. idio:function:: libc/fchmod fd mode in C: :samp:`fchmod ({fd}, {mode})` a wrapper to libc :manpage:`fchmod(2)` :param fd: file descriptor :type fd: C/int :param mode: mode flags :type mode: libc/mode_t :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/fchmodat`: .. idio:function:: libc/fchmodat dirfd pathname mode [flag ...] in C: :samp:`fchmodat ({dirfd}, {pathname}, {mode}, {flags})` a wrapper to libc :manpage:`fchmodat(2)` :param dirfd: file descriptor for a directory :type dirfd: C/int :param pathname: pathname :type pathname: string :param mode: mode flags :type mode: libc/mode_t :param flags: see below, default none :type flags: C/int :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: The following value can be used for `dirfd`: ``AT_FDCWD`` The following values are defined for `flags`, they can be ``C/|``-bitwise OR'd together or passed as extra arguments: ``AT_SYMLINK_NOFOLLOW`` .. note:: ``fchmodat`` is not available on all systems. Use the ``IDIO_NO_FCHMODAT`` feature in :ref:`cond-expand `. .. _`libc/fchown`: .. idio:function:: libc/fchown fd owner group in C: :samp:`fchown ({fd}, {owner}, {group})` a wrapper to libc :manpage:`fchown(2)` :param fd: file descriptor :type fd: C/int :param owner: User ID :type owner: libc/uid_t :param group: Group ID :type group: libc/gid_t :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/fchownat`: .. idio:function:: libc/fchownat dirfd pathname owner group [flag ...] in C: :samp:`fchownat ({dirfd}, {pathname}, {owner}, {group}, {flags})` a wrapper to libc :manpage:`fchownat(2)` :param dirfd: file descriptor for a directory :type dirfd: C/int :param pathname: pathname :type pathname: string :param owner: user ID :type owner: libc/uid_t :param group: group ID :type group: libc/gid_t :param flags: see below, default none :type flags: C/int, optional :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: The following value can be used for `dirfd`: ``AT_FDCWD`` The following values are defined for `flags`, they can be ``C/|``-bitwise OR'd together or passed as extra arguments: ``AT_SYMLINK_NOFOLLOW`` .. note:: ``fchownat`` is not available on all systems. Use the ``IDIO_NO_FCHOWNAT`` feature in :ref:`cond-expand `. .. _`libc/fcntl`: .. idio:function:: libc/fcntl fd cmd [args] in C, :samp:`fcntl ({fd}, {cmd}[, {args}])` a wrapper to libc :manpage:`fcntl(2)` :param fd: file descriptor :type fd: C/int :param cmd: fcntl command :type cmd: C/int :param args: fcntl command args :type args: list :return: appropriate value :rtype: C/int :raises ^system-error: Supported commands include: ``libc/F_DUPFD`` ``libc/F_DUPFD_CLOEXEC`` (if available) ``libc/F_GETFL`` ``libc/F_SETFL`` .. _`libc/fork`: .. idio:function:: libc/fork in C, :samp:`fork ()` a wrapper to libc :manpage:`fork(2)` :return: 0 or Process ID of child :rtype: libc/pid_t :raises ^system-error: ``fork`` will update :ref:`PID ` and :ref:`PPID ` in the child process. .. _`libc/fstat`: .. idio:function:: libc/fstat fd in C, :samp:`fstat ({fd})` a wrapper to libc :manpage:`fstat(2)` :param fd: file descriptor :type fd: C/int :return: :ref:`struct-stat ` :rtype: C/pointer :raises ^system-error: .. _`libc/fstatat`: .. idio:function:: libc/fstatat dirfd pathname [flag ...] in C: :samp:`fstatat ({dirfd}, {pathname}, statbuf, {flags})` a wrapper to libc :manpage:`fstatat(2)` :param dirfd: file descriptor for a directory :type dirfd: C/int :param pathname: pathname :type pathname: string :param flags: see below, default none :type flags: C/int, optional :return: :ref:`struct-stat ` :rtype: C/pointer :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: The following value can be used for `dirfd`: ``AT_FDCWD`` The following values are defined for `flags`, they can be ``C/|``-bitwise OR'd together or passed as extra arguments: ``AT_SYMLINK_NOFOLLOW`` .. note:: ``fstatat`` is not available on all systems. Use the ``IDIO_NO_FSTATAT`` feature in :ref:`cond-expand `. .. _`libc/fstatvfs`: .. idio:function:: libc/fstatvfs fd in C: :samp:`fstatvfs ({fd})` a wrapper to libc :manpage:`fstatvfs(3)` :param fd: file descriptor :type fd: C/int :return: :ref:`struct-statvfs ` :rtype: C/pointer :raises ^system-error: .. _`libc/fsync`: .. idio:function:: libc/fsync fd in C: :samp:`fsync ({fd})` a wrapper to libc :manpage:`fsync(2)` :param fd: file descriptor :type fd: C/int :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/ftruncate`: .. idio:function:: libc/ftruncate fd length in C: :samp:`ftruncate ({fd}, {length})` a wrapper to libc :manpage:`ftruncate(2)` :param fd: file descriptor :type fd: C/int :param length: length :type length: libc/off_t :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/futimes`: .. idio:function:: libc/futimes fd atime mtime in C: :samp:`futimes ({fd}, ({atime}, {mtime}))` a wrapper to libc :manpage:`futimes(3)` :param fd: file descriptor :type fd: C/int :param atime: :ref:`struct-timeval ` :type atime: C/pointer :param mtime: :ref:`struct-timeval ` :type mtime: C/pointer :return: 0 :rtype: C/int :raises ^system-error: .. note:: ``futimes`` is not available on all systems. Use the ``IDIO_NO_FUTIMES`` feature in :ref:`cond-expand `. .. seealso:: :ref:`futimesat ` .. _`libc/futimesat`: .. idio:function:: libc/futimesat dirfd pathname atime mtime in C: :samp:`futimesat ({dirfd}, {pathname}, ({atime}, {mtime}))` a wrapper to libc :manpage:`futimesat(2)` :param dirfd: file descriptor for a directory :type dirfd: C/int :param pathname: pathname :type pathname: string :param atime: :ref:`struct-timeval ` :type atime: C/pointer :param mtime: :ref:`struct-timeval ` :type mtime: C/pointer :return: 0 :rtype: C/int :raises ^system-error: .. note:: ``futimesat`` is not available on all systems. Use the ``IDIO_NO_FUTIMESAT`` feature in :ref:`cond-expand `. .. seealso:: :ref:`futimes ` .. _`libc/getcwd`: .. idio:function:: libc/getcwd in C, :samp:`getcwd (buf, size)` a wrapper to libc :manpage:`getcwd(3)` :return: current working directory :rtype: pathname :raises ^system-error: .. note:: The returned value is limited to ``libc/PATH_MAX`` bytes .. _`libc/getegid`: .. idio:function:: libc/getegid in C: :samp:`getegid ()` a wrapper to libc :manpage:`getegid(2)` :return: effective group ID :rtype: libc/gid_t .. _`libc/geteuid`: .. idio:function:: libc/geteuid in C: :samp:`geteuid ()` a wrapper to libc :manpage:`geteuid(2)` :return: effective user ID :rtype: libc/uid_t .. _`libc/getgid`: .. idio:function:: libc/getgid in C: :samp:`getgid ()` a wrapper to libc :manpage:`getgid(2)` :return: real group ID :rtype: libc/gid_t .. _`libc/getgrgid`: .. idio:function:: libc/getgrgid gid in C: :samp:`getgrgid ({gid})` a wrapper to libc :manpage:`getgrgid(3)` :param gid: group ID :type gid: unsigned fixnum or libc/gid_t :return: :ref:`struct-group ` or ``#f`` :rtype: C/pointer :raises ^system-error: .. _`libc/getgrnam`: .. idio:function:: libc/getgrnam name in C: :samp:`getgrnam ({name})` a wrapper to libc :manpage:`getgrnam(3)` :param name: group name :type name: string :return: :ref:`struct-group ` or ``#f`` :rtype: C/pointer :raises ^rt-libc-format-error: if `name` contains an ASCII NUL :raises ^system-error: .. _`libc/getlogin`: .. idio:function:: libc/getlogin in C: :samp:`getlogin ()` a wrapper to libc :manpage:`getlogin(3)` :return: user name :rtype: string .. _`libc/getpgid`: .. idio:function:: libc/getpgid pid in C, :samp:`getpgid ({pid})` a wrapper to libc :manpage:`getpgid(2)` :param pid: progress ID :type pid: libc/pid_t :return: Process Group ID :rtype: libc/pid_t :raises ^system-error: .. _`libc/getpgrp`: .. idio:function:: libc/getpgrp in C, :samp:`getpgrp ()` a wrapper to libc :manpage:`getpgrp(2)` :return: Process Group ID :rtype: libc/pid_t :raises ^system-error: .. _`libc/getpid`: .. idio:function:: libc/getpid in C, :samp:`getpid ()` a wrapper to libc :manpage:`getpid(2)` :return: Process ID :rtype: libc/pid_t :raises ^system-error: .. _`libc/getppid`: .. idio:function:: libc/getppid in C, :samp:`getppid ()` a wrapper to libc :manpage:`getppid(2)` :return: Parent Process ID :rtype: libc/pid_t :raises ^system-error: .. _`libc/getpriority`: .. idio:function:: libc/getpriority which who in C: :samp:`getpriority ({which}, {who})` a wrapper to libc :manpage:`getpriority(2)` :param which: see below :type which: C/int :param who: dependent on `which` :type who: libc/id_t :return: nice value :rtype: C/int :raises ^system-error: `which` should be one of the values: ``PRIO_PROCESS``, ``PRIO_PGRP`` or ``PRIO_USER``. `who` is then an appropriate value. .. _`libc/getpwuid`: .. idio:function:: libc/getpwuid uid in C: :samp:`getpwuid ({uid})` a wrapper to libc :manpage:`getpwuid(3)` :param uid: user ID :type uid: unsigned fixnum or libc/uid_t :return: :ref:`struct-passwd ` or ``#f`` :rtype: C/pointer :raises ^system-error: .. _`libc/getpwnam`: .. idio:function:: libc/getpwnam name in C: :samp:`getpwnam ({name})` a wrapper to libc :manpage:`getpwnam(3)` :param name: user name :type name: string :return: :ref:`struct-passwd ` or ``#f`` :rtype: C/pointer :raises ^rt-libc-format-error: if `name` contains an ASCII NUL :raises ^system-error: .. _`libc/getrlimit`: .. idio:function:: libc/getrlimit res a more convenient :manpage:`getrlimit(2)` which can use a :samp:`:{nickname}` keyword, eg. ``:NOFILE`` for ``libc/RLIMIT_NOFILE`` :param res: either the ``libc/RLIMIT_*`` symbol or C/int or :samp:`:{nickname}` keyword :return: :ref:`struct-rlimit ` :rtype: C/pointer :raises ^system-error: The resource names follow C conventions such as ``libc/RLIMIT_AS`` and ``libc/RLIMIT_NOFILE``. .. seealso:: :ref:`rlimit-names ` .. _`libc/getrusage`: .. idio:function:: libc/getrusage who in C, :samp:`getrusage ({who}, rusage)` a wrapper to libc :manpage:`getrusage(2)` :param who: who, see below :type who: C/int :return: :ref:`struct-rusage ` :rtype: C/pointer :raises ^system-error: The parameter `who` refers to ``libc/RUSAGE_SELF`` or ``libc/RUSAGE_CHILDREN`` .. _`libc/getsid`: .. idio:function:: libc/getsid pid in C, :samp:`getsid ({pid})` a wrapper to libc :manpage:`getsid(2)` :param pid: Process ID :type pid: libc/pid_t :return: Session ID :rtype: libc/pid_t :raises ^system-error: .. _`libc/gettimeofday`: .. idio:function:: libc/gettimeofday in C, :samp:`gettimeofday ()` a wrapper to libc :manpage:`gettimeofday(2)` :return: :ref:`struct-timeval ` :rtype: C/pointer :raises ^system-error: .. note:: The struct timezone parameter is not used. .. _`libc/getuid`: .. idio:function:: libc/getuid in C: :samp:`getuid ()` a wrapper to libc :manpage:`getuid(2)` :return: real user ID :rtype: libc/uid_t .. _`libc/gmtime`: .. idio:function:: libc/gmtime [t] in C, :samp:`gmtime ({t})` a wrapper to libc :manpage:`gmtime(3)` :param t: time in seconds since epoch, defaults to the result of :manpage:`time(2)` :type t: libc/time_t, optional :return: :ref:`struct-tm ` :rtype: C/pointer :raises ^system-error: .. _`libc/grantpt`: .. idio:function:: libc/grantpt fd in C, :samp:`grantpt ({fd})` a wrapper to libc :manpage:`grantpt(3)` :param fd: fd to grantpt :type fd: C/int :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/ioctl`: .. idio:function:: libc/ioctl fd cmd [args] in C, :samp:`ioctl ({fd}, {cmd}[, {args}])` a wrapper to libc :manpage:`ioctl(2)` :param fd: file descriptor :type fd: C/int :param cmd: ioctl command :type cmd: C/int :param args: ioctl command args :type args: list :return: appropriate value :rtype: C/int :raises ^system-error: Supported commands include: ``libc/I_PUSH`` .. _`libc/isatty`: .. idio:function:: libc/isatty fd in C, :samp:`isatty ({fd})` a wrapper to libc :manpage:`isatty(3)` :param fd: file descriptor :type fd: C/int :return: ``#t`` or ``#f`` :rtype: boolean :raises ^system-error: A strictly conforming ``isatty`` would raise a ^system-error for ``ENOTTY`` however this wrapper returns ``#f`` in that case but raises ^system-error for any other :manpage:`isatty(3)` error. .. warning:: Not all operating systems set ``errno`` when :manpage:`isatty(3)` returns 0, ``isatty`` also returns ``#f`` in that case. .. _`libc/kill`: .. idio:function:: libc/kill pid sig in C, :samp:`kill ({pid}, {sig})` a wrapper to libc :manpage:`kill(2)` :param pid: Process ID :type pid: libc/pid_t :param fd: signal number :type fd: C/int :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/killpg`: .. idio:function:: libc/killpg pgrp sig in C, :samp:`killpg ({pgrp}, {sig})` a wrapper to libc :manpage:`killpg(3)` :param pgrp: Process Group ID :type pgrp: libc/pid_t :param sig: signal number :type sig: C/int :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/link`: .. idio:function:: libc/link oldpath newpath in C: :samp:`link ({oldpath}, {newpath})` a wrapper to libc :manpage:`link(2)` :param oldpath: existing file name :type oldpath: string :param newpath: new file name :type newpath: string :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `oldpath` or `newpath` contain an ASCII NUL :raises ^system-error: .. _`libc/linkat`: .. idio:function:: libc/linkat olddirfd oldpath newdirfd newpath [flag ...] in C: :samp:`linkat ({olddirfd}, {oldpath}, {newdirfd}, {newpath}, {flags})` a wrapper to libc :manpage:`linkat(2)` :param olddirfd: file descriptor for a directory :type olddirfd: C/int :param oldpath: existing file name :type oldpath: string :param newdirfd: file descriptor for a directory :type newdirfd: C/int :param newpath: new file name :type newpath: string :param flags: see below, default none :type flags: C/int, optional :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: The following value can be used for `dirfd`: ``AT_FDCWD`` The following values are defined for `flags`, they can be ``C/|``-bitwise OR'd together or passed as extra arguments: ``AT_SYMLINK_FOLLOW`` .. note:: ``linkat`` is not available on all systems. Use the ``IDIO_NO_LINKAT`` feature in :ref:`cond-expand `. .. _`libc/localtime`: .. idio:function:: libc/localtime [t] in C, :samp:`localtime ({t})` a wrapper to libc :manpage:`localtime(3)` :param t: time in seconds since epoch, defaults to the result of :manpage:`time(2)` :type t: libc/time_t, optional :return: :ref:`struct-tm ` :rtype: C/pointer :raises ^system-error: .. _`libc/lockf`: .. idio:function:: libc/lockf fd cmd len in C: :samp:`lockf ({fd}, {cmd}, {len})` a wrapper to libc :manpage:`lockf(3)` :param fd: file descriptor :type fd: C/int :param cmd: see below :type cmd: C/int :param len: relative offset :type len: libc/off_t :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/lstat`: .. idio:function:: libc/lstat pathname in C, :samp:`lstat ({pathname})` a wrapper to libc :manpage:`lstat(2)` :param pathname: filename to stat :type pathname: string :return: :ref:`struct-stat ` :rtype: C/pointer :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: .. _`libc/mkdir`: .. idio:function:: libc/mkdir pathname mode in C, :samp:`mkdir ({pathname}, {mode})` a wrapper to libc :manpage:`mkdir(2)` :param pathname: directory name :type pathname: string :param mode: mode flags :type mode: libc/mode_t :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: .. _`libc/mkdirat`: .. idio:function:: libc/mkdirat dirfd pathname mode in C: :samp:`mkdirat ({dirfd}, {pathname}, {mode})` a wrapper to libc :manpage:`mkdirat(2)` :param dirfd: file descriptor for a directory :type dirfd: C/int :param pathname: pathname :type pathname: string :param mode: mode flags :type mode: libc/mode_t :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: The following value can be used for `dirfd`: ``AT_FDCWD`` .. _`libc/mkdtemp`: .. idio:function:: libc/mkdtemp template in C, :samp:`mkdtemp ({template})` a wrapper to libc :manpage:`mkdtemp(3)` :param template: directory template :type template: string :return: modified template :rtype: pathname :raises ^rt-libc-format-error: if `template` contains an ASCII NUL :raises ^system-error: .. _`libc/mkfifo`: .. idio:function:: libc/mkfifo path mode in C, :samp:`mkfifo ({path}, {mode})` a wrapper to libc :manpage:`mkfifo(2)` :param path: filename of FIFO :type path: string :param mode: mode flags :type mode: libc/mode_t :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `path` contains an ASCII NUL :raises ^system-error: .. _`libc/mkstemp`: .. idio:function:: libc/mkstemp template in C, :samp:`mkstemp ({template})` a wrapper to libc :manpage:`mkstemp(3)` :param template: filename template :type template: string :return: (fd filename) :rtype: list (C/int, pathname) :raises ^rt-libc-format-error: if `template` contains an ASCII NUL :raises ^system-error: .. _`libc/mktime`: .. idio:function:: libc/mktime tm in C, :samp:`mktime ({tm})` a wrapper to libc :manpage:`mktime(3)` :param tm: time structure :type tm: :ref:`struct-tm ` :return: calendar time :rtype: libc/time_t :raises ^system-error: .. _`libc/nanosleep`: .. idio:function:: libc/nanosleep req in C, :samp:`nanosleep ({req}, rem)` a wrapper to libc :manpage:`nanosleep(2)` :param req: see below :type req: :ref:`struct-timespec ` or a list :return: (`completed?` *rem*) :rtype: list :raises ^system-error: *rem* is a :ref:`struct-timespec ` ``EINTR`` will return :samp:`(#f {rem})` otherwise return :samp:`(#t {rem})` `req` can be a list of :samp:`({sec} [{nsec}])` where `sec` can be a :ref:`libc/time_t ` | fixnum | bignum and `nsec` can be a ``C/long`` | fixnum | bignum .. _`libc/open`: .. idio:function:: libc/open pathname flags [mode] in C, :samp:`open ({pathname}, {mode})` a wrapper to libc :manpage:`open(2)` :param pathname: filename :type pathname: string :param flags: access/creation flags :type flags: C/int :param mode: mode flags, defaults to 0 :type mode: libc/mode_t, optional :return: file descriptor :rtype: C/int :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: .. _`libc/openat`: .. idio:function:: libc/openat dirfd pathname flags [mode] in C: :samp:`openat ({dirfd}, {pathname}, {flags}, {mode})` a wrapper to libc :manpage:`openat(2)` :param dirfd: file descriptor for a directory :type dirfd: C/int :param pathname: pathname :type pathname: string :param flags: access/creation flags :type flags: C/int :param mode: mode flags, defaults to 0 :type mode: libc/mode_t, optional :return: file descriptor :rtype: C/int :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: .. _`libc/pipe`: .. idio:function:: libc/pipe in C, :samp:`pipe (pipefd)` a wrapper to libc :manpage:`pipe(2)` :return: pointer to pipe array :rtype: C/pointer :raises ^system-error: *pipefd* is a `C/pointer` to a C ``int[2]``. .. seealso:: :ref:`pipe-reader ` and :ref:`pipe-writer ` for accessors to *pipefd*. .. _`libc/pipe-reader`: .. idio:function:: libc/pipe-reader pipefd Return the read end of the pipe array :param pipefd: pointer to pipe array :type pipefd: C/pointer :return: read end of the pipe array :rtype: C/int .. seealso:: :ref:`pipe ` for a constructor of the pipe array. .. _`libc/pipe-writer`: .. idio:function:: libc/pipe-writer pipefd Return the write end of the pipe array :param pipefd: pointer to pipe array :type pipefd: C/pointer :return: write end of the pipe array :rtype: C/int .. seealso:: :ref:`pipe ` for a constructor of the pipe array. .. _`libc/posix_openpt`: .. idio:function:: libc/posix_openpt [flags] in C, :samp:`posix_openpt ({flags})` a wrapper to libc :manpage:`posix_openpt(3)` :param flags: flags to posix_openpt, defaults to ``O_RDWR [| O_NOCTTY]`` :type flags: C/int, optional :return: file descriptor for master :rtype: C/int :raises ^system-error: .. note:: ``O_NOCTTY`` is not available on all systems. .. _`libc/pread`: .. idio:function:: libc/pread fd offset [count] in C: :samp:`pread ({fd}, buf, {count}, {offset})` a wrapper to libc :manpage:`pread(2)` :param fd: file descriptor :type fd: C/int :param offset: offset :type offset: libc/off_t :param count: number of bytes to read, defaults to ``libc/BUFSIZ`` :type count: fixnum or libc/size_t, optional :return: string of bytes read or see below :rtype: octet string or see below :raises ^system-error: If :manpage:`pread(2)` returned 0 then this code returns ``#``. If :manpage:`pread(2)` indicated ``EAGAIN`` then this code returns #f. .. seealso:: :ref:`octet-string->string string>` .. _`libc/ptsname`: .. idio:function:: libc/ptsname fd in C, :samp:`ptsname ({fd})` a wrapper to libc :manpage:`ptsname(3)` :param fd: fd to ptsname :type fd: C/int :return: ptsname :rtype: pathname :raises ^system-error: .. _`libc/pwrite`: .. idio:function:: libc/pwrite fd str offset in C: :samp:`pwrite ({fd}, {str}, {offset})` a wrapper to libc :manpage:`pwrite(2)` :param fd: file descriptor :type fd: C/int :param str: string :type buf: string :param offset: offset :type offset: libc/off_t :return: number of bytes written :rtype: libc/ssize_t :raises ^system-error: .. _`libc/read`: .. idio:function:: libc/read fd [count] in C, :samp:`read ({fd}, buf, {count})` a wrapper to libc :manpage:`read(2)` :param fd: file descriptor :type fd: C/int :param count: number of bytes to read, defaults to ``libc/BUFSIZ`` :type count: fixnum or libc/size_t, optional :return: string of bytes read or see below :rtype: octet string or see below :raises ^system-error: If :manpage:`read(2)` returned 0 then this code returns ``#``. If :manpage:`read(2)` indicated ``EAGAIN`` then this code returns #f. .. seealso:: :ref:`octet-string->string string>` .. _`libc/readlink`: .. idio:function:: libc/readlink pathname in C: :samp:`readlink ({pathname}, buf, bufsiz)` a wrapper to libc :manpage:`readlink(2)` :param pathname: pathname :type pathname: string :return: contents of symlink :rtype: pathname :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: .. _`libc/readlinkat`: .. idio:function:: libc/readlinkat dirfd pathname in C: :samp:`readlinkat ({dirfd}, {pathname}, buf, bufsiz)` a wrapper to libc :manpage:`readlinkat(2)` :param dirfd: file descriptor for a directory :type dirfd: C/int :param pathname: pathname :type pathname: string :return: contents of symlink :rtype: pathname :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: .. _`libc/rename`: .. idio:function:: libc/rename oldpath newpath in C: :samp:`rename ({oldpath}, {newpath})` a wrapper to libc :manpage:`rename(2)` :param oldpath: existing file name :type oldpath: string :param newpath: new file name :type newpath: string :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `oldpath` or `newpath` contain an ASCII NUL :raises ^system-error: .. _`libc/renameat`: .. idio:function:: libc/renameat olddirfd oldpath newdirfd newpath in C: :samp:`renameat ({olddirfd}, {oldpath}, {newdirfd}, {newpath})` a wrapper to libc :manpage:`renameat(2)` :param olddirfd: file descriptor for a directory :type olddirfd: C/int :param oldpath: pathname :type oldpath: string :param newdirfd: file descriptor for a directory :type newdirfd: C/int :param newpath: pathname :type newpath: string :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `oldpath` or `newpath` contain an ASCII NUL :raises ^system-error: .. _`libc/rmdir`: .. idio:function:: libc/rmdir pathname in C, :samp:`rmdir ({pathname})` a wrapper to libc :manpage:`rmdir(2)` :param pathname: directory to remove :type pathname: string :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: .. _`libc/select`: .. idio:function:: libc/select rlist wlist elist [timeout] Call :manpage:`select(2)` for `timeout` microseconds :param rlist: a list of selectable entities for read events :type rlist: list :param wlist: a list of selectable entities for write events :type wlist: list :param elist: a list of selectable entities for exception events :type elist: list :param timeout: timeout in microseconds, defaults to ``#n`` :type timeout: fixnum, bignum or :ref:`libc/struct-timeval ` :return: list of three lists of events, see below :rtype: list :raises ^rt-parameter-type-error: :raises ^system-error: The return value is a list of three lists of ready objects, derived from the first three arguments. Selectable entities are file descriptors (C/int) and file descriptor handles. .. _`libc/setegid`: .. idio:function:: libc/setegid egid in C: :samp:`setegid ({egid})` a wrapper to libc :manpage:`setegid(2)` :param egid: effective group ID :type egid: libc/gid_t :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/seteuid`: .. idio:function:: libc/seteuid euid in C: :samp:`seteuid ({euid})` a wrapper to libc :manpage:`seteuid(2)` :param euid: effective user ID :type euid: libc/uid_t :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/setgid`: .. idio:function:: libc/setgid gid in C: :samp:`setgid ({gid})` a wrapper to libc :manpage:`setgid(2)` :param gid: group ID :type gid: libc/gid_t :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/setpgid`: .. idio:function:: libc/setpgid pid pgid in C, :samp:`setpgid ({pid}, {pgid})` a wrapper to libc :manpage:`setpgid(2)` :param pid: process ID :type pid: libc/pid_t :param pgid: Process Group ID :type pgid: libc/pid_t :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/setpriority`: .. idio:function:: libc/setpriority which who prio in C: :samp:`setpriority ({which}, {who}, {prio})` a wrapper to libc :manpage:`setpriority(2)` :param which: see below :type which: C/int :param who: dependent on `which` :type who: libc/id_t :param prio: priority :type prio: C/int :return: 0 :rtype: C/int :raises ^system-error: `which` should be one of the values: ``PRIO_PROCESS``, ``PRIO_PGRP`` or ``PRIO_USER``. `who` is then an appropriate value. .. _`libc/setregid`: .. idio:function:: libc/setregid rgid egid in C: :samp:`setregid ({rgid}, {egid})` a wrapper to libc :manpage:`setregid(2)` :param rgid: real group ID :type rgid: libc/gid_t :param egid: effective group ID :type egid: libc/gid_t :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/setresgid`: .. idio:function:: libc/setresgid rgid egid sgid in C: :samp:`setresgid ({rgid}, {egid}, {sgid})` a wrapper to libc :manpage:`setresgid(2)` :param rgid: real group ID :type rgid: libc/gid_t :param egid: effective group ID :type egid: libc/gid_t :param sgid: saved group ID :type sgid: libc/gid_t :return: 0 :rtype: C/int :raises ^system-error: .. note:: ``setresgid`` is not available on all systems. Use the ``IDIO_NO_SET_SAVED_IDS`` feature in :ref:`cond-expand `. .. _`libc/setresuid`: .. idio:function:: libc/setresuid ruid euid suid in C: :samp:`setresuid ({ruid}, {euid}, {suid})` a wrapper to libc :manpage:`setresuid(2)` :param ruid: real user ID :type ruid: libc/uid_t :param euid: effective user ID :type euid: libc/uid_t :param suid: saved user ID :type suid: libc/uid_t :return: 0 :rtype: C/int :raises ^system-error: .. note:: ``setresuid`` is not available on all systems. Use the ``IDIO_NO_SET_SAVED_IDS`` feature in :ref:`cond-expand `. .. _`libc/setreuid`: .. idio:function:: libc/setreuid ruid euid in C: :samp:`setreuid ({ruid}, {euid})` a wrapper to libc :manpage:`setreuid(2)` :param ruid: real user ID :type ruid: libc/uid_t :param euid: effective user ID :type euid: libc/uid_t :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/setrlimit`: .. idio:function:: libc/setrlimit res rlim a more convenient :manpage:`setrlimit(2)` which can use a :samp:`:{nickname}` keyword, eg. ``:NOFILE`` for ``libc/RLIMIT_NOFILE`` :param res: either the ``libc/RLIMIT_*`` symbol or C/int or :samp:`:{nickname}` keyword :param rlim: :ref:`struct-rlimit ` :type rlim: C/pointer :return: ``#`` :raises ^system-error: The resource names follow C conventions such as ``libc/RLIMIT_AS`` and ``libc/RLIMIT_NOFILE``. .. seealso:: :ref:`getrlimit ` to obtain a `struct-rlimit` and :ref:`rlimit-names ` .. _`libc/setsid`: .. idio:function:: libc/setsid in C, :samp:`setsid ()` a wrapper to libc :manpage:`setsid(2)` :return: Process Group ID of progress group :rtype: libc/pid_t :raises ^system-error: .. _`libc/setuid`: .. idio:function:: libc/setuid uid in C: :samp:`setuid ({uid})` a wrapper to libc :manpage:`setuid(2)` :param uid: user ID :type uid: libc/uid_t :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/signal`: .. idio:function:: libc/signal sig handler in C, :samp:`signal ({sig}, {handler})` a wrapper to libc :manpage:`signal(2)` :param sig: signal :type sig: C/int :param handler: signal disposition :type handler: C/pointer :return: previous disposition :rtype: C/pointer :raises ^system-error: The following dispositions are defined: ``libc/SIG_IGN`` ``libc/SIG_DFL`` .. _`libc/signal-handler`: .. idio:function:: libc/signal-handler sig signal-handler (sig) A helper function to advise of the current disposition for a given signal. :param sig: signal :type sig: C/int :return: current disposition :rtype: C/pointer :raises ^system-error: The following dispositions are defined: ``libc/SIG_IGN`` ``libc/SIG_DFL`` :Example: .. code-block:: idio C/== (libc/signal-handler libc/SIGPIPE) libc/SIG_IGN ; #t or #f .. _`libc/sleep`: .. idio:function:: libc/sleep seconds in C, :samp:`sleep ({seconds})` a wrapper to libc :manpage:`sleep(3)` :param seconds: seconds to sleep :type seconds: unsigned fixnum or C/uint :return: 0 or the number of seconds left if interrupted :rtype: C/uint .. _`libc/stat`: .. idio:function:: libc/stat pathname in C, :samp:`stat ({pathname})` a wrapper to libc :manpage:`stat(2)` :param pathname: filename to stat :type pathname: string :return: :ref:`struct-stat ` :rtype: C/pointer :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: .. _`libc/statvfs`: .. idio:function:: libc/statvfs path in C: :samp:`statvfs ({path})` a wrapper to libc :manpage:`statvfs(3)` :param path: filename to stat :type path: string :return: :ref:`struct-statvfs ` :rtype: C/pointer :raises ^rt-libc-format-error: if `path` contains an ASCII NUL :raises ^system-error: .. _`libc/strerrno`: .. idio:function:: libc/strerrno errnum return the error name of `errnum` :param errnum: error number :type errnum: C/int :return: error name :rtype: string Identical to :ref:`errno-name `. .. _`libc/strerror`: .. idio:function:: libc/strerror errnum in C, :samp:`strerror ({errnum})` a wrapper to libc :manpage:`strerror(3)` :param errnum: error code to describe :type errnum: C/int :return: string describing `errnum` :rtype: string :raises ^system-error: .. _`libc/strftime`: .. idio:function:: libc/strftime format tm in C, :samp:`strftime ({format}, {tm})` a wrapper to libc :manpage:`strftime(3)` :param format: format string :type format: string :param tm: time structure :type tm: :ref:`struct-tm ` :return: formatted time :rtype: string :raises ^rt-libc-format-error: if `format` contains an ASCII NUL .. note:: Internally, ``libc/BUFSIZ`` is used for the maximum string size .. seealso:: :ref:`gmtime `, :ref:`localtime `, :ref:`strptime ` to obtain a `struct-tm`. .. _`libc/strptime`: .. idio:function:: libc/strptime s format in C, :samp:`strptime ({s}, {format})` a wrapper to libc :manpage:`strptime(3)` :param s: time string :type s: string :param format: format string :type format: string :return: time structure :rtype: C :ref:`struct-tm ` :raises ^rt-libc-format-error: if `s` or `format` contain an ASCII NUL .. _`libc/strsignal`: .. idio:function:: libc/strsignal sig in C, :samp:`strsignal ({sig})` a wrapper to libc :manpage:`strsignal(3)` :param sig: signal number to describe :type sig: C/int :return: string describing `sig` :rtype: string On some systems (SunOS) ``#n`` may be returned for an invalid signal number. .. _`libc/symlink`: .. idio:function:: libc/symlink target linkpath in C: :samp:`symlink ({target}, {linkpath})` a wrapper to libc :manpage:`symlink(2)` :param target: existing file name :type target: string :param linkpath: new file name :type linkpath: string :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `target` or `linkpath` contain an ASCII NUL :raises ^system-error: .. _`libc/symlinkat`: .. idio:function:: libc/symlinkat target newdirfd linkpath in C: :samp:`symlinkat ({target}, {newdirfd}, {linkpath})` a wrapper to libc :manpage:`symlinkat(2)` :param target: existing file name :type target: string :param newdirfd: file descriptor for a directory :type newdirfd: C/int :param linkpath: new file name :type linkpath: string :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `target` or `linkpath` contain an ASCII NUL :raises ^system-error: .. _`libc/sync`: .. idio:function:: libc/sync in C: :samp:`sync ()` a wrapper to libc :manpage:`sync(2)` :return: ``#`` .. _`libc/tcgetattr`: .. idio:function:: libc/tcgetattr fd in C, :samp:`tcgetattr ({fd}, termiosp)` a wrapper to libc :manpage:`tcgetattr(3)` :param fd: file descriptor :type fd: C/int :return: :ref:`struct-termios ` :rtype: C/pointer :raises ^system-error: .. _`libc/tcgetpgrp`: .. idio:function:: libc/tcgetpgrp fd in C, :samp:`tcgetpgrp ({fd})` a wrapper to libc :manpage:`tcgetpgrp(3)` :param fd: file descriptor :type fd: C/int :return: Process ID :rtype: libc/pid_t :raises ^system-error: .. _`libc/tcsetattr`: .. idio:function:: libc/tcsetattr fd options termios in C, :samp:`tcsetattr ({fd}, {options}, {termios})` a wrapper to libc :manpage:`tcsetattr(3)` :param fd: file descriptor :type fd: C/int :param options: see below :type options: C/int :param termios: :ref:`struct-termios ` :type termios: C/pointer :return: 0 :rtype: C/int :raises ^system-error: The following options are defined: ``libc/TCSADRAIN`` ``libc/TCSAFLUSH`` .. seealso:: :ref:`tcgetattr ` for obtaining a :ref:`struct-termios `. .. _`libc/tcsetpgrp`: .. idio:function:: libc/tcsetpgrp fd pgrp in C, :samp:`tcsetpgrp ({fd}, {pgrp})` a wrapper to libc :manpage:`tcsetpgrp(3)` :param fd: file descriptor :type fd: C/int :param pgrp: Process Group ID :type pgrp: libc/pid_t :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/time`: .. idio:function:: libc/time in C, :samp:`time ()` a wrapper to libc :manpage:`time(2)` :return: seconds since epoch :rtype: libc/time_t :raises ^system-error: .. _`libc/times`: .. idio:function:: libc/times in C, :samp:`times ()` a wrapper to libc :manpage:`times(3)` :return: (clock_t, :ref:`struct-tms `) :rtype: list :raises ^system-error: :manpage:`times(3)` is complicated because we need to return the ``struct tms`` that the user would have passed in as a pointer and the ``clock_t``, elapsed real time, that :manpage:`times(3)` returns. All fields are in clock ticks for which ``sysconf(_SC_CLK_TCK)`` is available for reference as ``libc/CLK_TCK``. .. _`libc/truncate`: .. idio:function:: libc/truncate path length in C: :samp:`truncate ({path}, {length})` a wrapper to libc :manpage:`truncate(2)` :param path: file name :type path: string :param length: length :type length: libc/off_t :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `path` contains an ASCII NUL :raises ^system-error: .. _`libc/ttyname`: .. idio:function:: libc/ttyname fd in C: :samp:`ttyname ({fd})` a wrapper to libc :manpage:`ttyname(3)` :param fd: terminal device file descriptor :type fd: C/int :return: pathname of the terminal device :rtype: pathname :raises ^system-error: .. _`libc/umask`: .. idio:function:: libc/umask mask in C: :samp:`umask ({mask})` a wrapper to libc :manpage:`umask(2)` :param mask: file mode creation mask :type mask: libc/mode_t :return: previous value :rtype: libc/mode_t .. _`libc/uname`: .. idio:function:: libc/uname in C, :samp:`uname (utsname)` a wrapper to libc :manpage:`uname(3)` :return: :ref:`struct-utsname ` :rtype: C/pointer :raises ^system-error: Not strictly useful at the moment. You might want to use :ref:`libc/idio-uname ` instead. .. _`libc/unlink`: .. idio:function:: libc/unlink pathname in C, :samp:`unlink ({pathname})` a wrapper to libc :manpage:`unlink(2)` :param pathname: filename to unlink :type pathname: string :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: .. _`libc/unlinkat`: .. idio:function:: libc/unlinkat dirfd pathname [flag ...] in C: :samp:`unlinkat ({dirfd}, {pathname}, {flags})` a wrapper to libc :manpage:`unlinkat(2)` :param dirfd: file descriptor for a directory :type dirfd: C/int :param pathname: pathname :type pathname: string :param flags: see below, default none :type flags: C/int, optional :return: 0 :rtype: C/int :raises ^rt-libc-format-error: if `pathname` contains an ASCII NUL :raises ^system-error: The following value can be used for `dirfd`: ``AT_FDCWD`` The following values are defined for `flags`, they can be ``C/|``-bitwise OR'd together or passed as extra arguments: ``AT_REMOVEDIR`` .. note:: ``unlinkat`` is not available on all systems. Use the ``IDIO_NO_UNLINKAT`` feature in :ref:`cond-expand `. .. _`libc/unlockpt`: .. idio:function:: libc/unlockpt fd in C, :samp:`unlockpt ({fd})` a wrapper to libc :manpage:`unlockpt(3)` :param fd: fd to unlockpt :type fd: C/int :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/utimes`: .. idio:function:: libc/utimes filename atime mtime in C: :samp:`utimes ({filename}, ({atime}, {mtime}))` a wrapper to libc :manpage:`utimes(2)` :param filename: filename :type filename: string :param atime: :ref:`struct-timeval ` :type atime: C/pointer :param mtime: :ref:`struct-timeval ` :type mtime: C/pointer :return: 0 :rtype: C/int :raises ^system-error: .. _`libc/wait`: .. idio:function:: libc/wait in C, :samp:`wait (status)` a wrapper to libc :manpage:`wait(2)` :return: list of (pid, *status*) :rtype: list of (libc/pid_t, C/pointer or ``#n``) :raises ^system-error: *status* is a `C/pointer` to a C ``int``. .. seealso:: :ref:`WIFEXITED `, :ref:`WEXITSTATUS `, :ref:`WIFSIGNALED `, :ref:`WTERMSIG `, :ref:`WIFSTOPPED ` for functions to manipulate *status*. .. _`libc/waitpid`: .. idio:function:: libc/waitpid pid [options] in C, :samp:`waitpid ({pid}, status[, {options}])` a wrapper to libc :manpage:`waitpid(2)` :param pid: Process ID :type pid: libc/pid_t :param options: see below :type options: C/int, optional :return: list of (pid, *status*) :rtype: list of (libc/pid_t, C/pointer or ``#n``) :raises ^system-error: ``libc/WAIT_ANY`` is defined as -1 for use as `pid`. The following options are defined: ``libc/WNOHANG`` ``libc/WUNTRACED`` Options will be IORed together *status* is a `C/pointer` to a C ``int``. .. seealso:: :ref:`WIFEXITED `, :ref:`WEXITSTATUS `, :ref:`WIFSIGNALED `, :ref:`WTERMSIG `, :ref:`WIFSTOPPED ` for functions to manipulate *status*. *Job Control* calls ``waitpid`` with ``WAIT_ANY`` (-1) and ``WNOHANG`` which means we can get a variety of results. The value returned is always a list of two elements. * If a child process has exited then ``waitpid`` returns :samp:`({pid}, {status})`. If :samp:`{pid}` is not identified as a process in the list of known jobs then the Job Control code enters it into a *stray pids* table along with its *status*. * If no child process has exited then ``waitpid`` returns :samp:`(0, {status})`. * If ``waitpid`` errors then * If the error is ``ECHILD`` then either the pid doesn't exist, is not a child process or the disposition of the ``SIGCHLD`` signal is ``SIG_IGN``. However, ``waitpid`` can look at the *stray pids* table and see if the queried `pid` exists and return that PID and its *status*. Otherwise we return ``(0 #n)``. * If the result is ``EINTR`` we can loop, re-invoking ``waitpid``. * Otherwise raise a ``^system-error``. .. _`libc/write`: .. idio:function:: libc/write fd str in C, :samp:`write ({fd}, {str})` a wrapper to libc :manpage:`write(2)` :param fd: file descriptor :type fd: C/int :param str: string :type str: string :return: number of bytes written :rtype: libc/ssize_t :raises ^system-error: .. _`libc/WEXITSTATUS`: .. idio:function:: libc/WEXITSTATUS status in C, :samp:`WEXITSTATUS ({status})` a wrapper to libc macro ``WEXITSTATUS``, see :manpage:`waitpid(2)` :param status: process status :type status: C/pointer :return: exit status of child :rtype: C/int .. _`libc/WIFEXITED`: .. idio:function:: libc/WIFEXITED status in C, :samp:`WIFEXITED ({status})` a wrapper to libc macro ``WIFEXITED``, see :manpage:`waitpid(2)` :param status: process status :type status: C/pointer :return: ``#t`` if the child exited normally or ``#f`` :rtype: boolean .. _`libc/WIFSIGNALED`: .. idio:function:: libc/WIFSIGNALED status in C, :samp:`WIFSIGNALED ({status})` a wrapper to libc macro ``WIFSIGNALED``, see :manpage:`waitpid(2)` :param status: process status :type status: C/pointer :return: ``#t`` if the child was terminated by a signal or ``#f`` :rtype: boolean .. _`libc/WIFSTOPPED`: .. idio:function:: libc/WIFSTOPPED status in C, :samp:`WIFSTOPPED ({status})` a wrapper to libc macro ``WIFSTOPPED``, see :manpage:`waitpid(2)` :param status: process status :type status: C/pointer :return: ``#t`` if the child was stopped by a signal or ``#f`` :rtype: boolean .. _`libc/WTERMSIG`: .. idio:function:: libc/WTERMSIG status in C, :samp:`WTERMSIG ({status})` a wrapper to libc macro ``WTERMSIG``, see :manpage:`waitpid(2)` :param status: process status :type status: C/pointer :return: signal number that terminated child :rtype: C/int .. _`libc/S_ISBLK`: .. idio:function:: libc/S_ISBLK mode does `mode` represent a block device? :param mode: mode from :manpage:`stat(2)` :type mode: libc/mode_t :return: ``#t`` or ``#f`` :rtype: boolean .. _`libc/S_ISCHR`: .. idio:function:: libc/S_ISCHR mode does `mode` represent a character device? :param mode: mode from :manpage:`stat(2)` :type mode: libc/mode_t :return: ``#t`` or ``#f`` :rtype: boolean .. _`libc/S_ISDIR`: .. idio:function:: libc/S_ISDIR mode does `mode` represent a directory? :param mode: mode from :manpage:`stat(2)` :type mode: libc/mode_t :return: ``#t`` or ``#f`` :rtype: boolean .. _`libc/S_ISFIFO`: .. idio:function:: libc/S_ISFIFO mode does `mode` represent a FIFO? :param mode: mode from :manpage:`stat(2)` :type mode: libc/mode_t :return: ``#t`` or ``#f`` :rtype: boolean .. _`libc/S_ISLNK`: .. idio:function:: libc/S_ISLNK mode does `mode` represent a symbolic link? :param mode: mode from :manpage:`stat(2)` :type mode: libc/mode_t :return: ``#t`` or ``#f`` :rtype: boolean .. _`libc/S_ISREG`: .. idio:function:: libc/S_ISREG mode does `mode` represent a regular file? :param mode: mode from :manpage:`stat(2)` :type mode: libc/mode_t :return: ``#t`` or ``#f`` :rtype: boolean .. _`libc/S_ISSOCK`: .. idio:function:: libc/S_ISSOCK mode does `mode` represent a socket? :param mode: mode from :manpage:`stat(2)` :type mode: libc/mode_t :return: ``#t`` or ``#f`` :rtype: boolean .. _`libc/stdin-fileno`: .. idio:function:: libc/stdin-fileno return the file descriptor of the current input handle :return: file descriptor or a list of a file descriptor If the current input handle is a string handle then its contents are written to a temporary file and a file descriptor open to that file is returned as the head of a list. The caller should close the file descriptor when the task is complete. .. _`libc/stdout-fileno`: .. idio:function:: libc/stdout-fileno return the file descriptor of the current output handle :return: file descriptor or a list of a file descriptor If the current output handle is a string handle then a temporary file is created and a file descriptor open to that file is returned as the head of a list. When the task is complete, the caller should rewind the file pointer and read the contents of the file back in before closing the file descriptor. .. _`libc/stderr-fileno`: .. idio:function:: libc/stderr-fileno return the file descriptor of the current error handle :return: file descriptor or a list of a file descriptor If the current error handle is a string handle then a temporary file is created and a file descriptor open to that file is returned as the head of a list. When the task is complete, the caller should rewind the file pointer and read the contents of the file back in before closing the file descriptor. .. _`libc/make-tmp-dir`: .. idio:function:: libc/make-tmp-dir [prefix] create a temporary directory and return its name :param prefix: prefix for directory name, defaults to ``"idio-tmp-"`` :type prefix: string, optional :return: directory name :rtype: pathname The directory is created in a temporary directory (commonly :file:`/tmp`). .. _`libc/make-tmp-fd`: .. idio:function:: libc/make-tmp-fd [prefix] create a temporary file and return an open file descriptor to it :param prefix: prefix for file name, defaults to ``"idio-tmp-"`` :type prefix: string, optional :return: open file descriptor :rtype: C/int The file is created in a temporary directory (commonly :file:`/tmp`). The file's name is unlinked therefore the returned file descriptor is the only reference to the file. .. _`libc/make-tmp-file`: .. idio:function:: libc/make-tmp-file [prefix] create a temporary file and return its name :param prefix: prefix for file name, defaults to ``"idio-tmp-"`` :type prefix: string, optional :return: file name :rtype: pathname The file is created in a temporary directory (commonly :file:`/tmp`). .. _`libc/make-tmp-file-handle`: .. idio:function:: libc/make-tmp-file-handle [prefix] create a temporary file and return an open file handle to it :param prefix: prefix for file name, defaults to ``"idio-tmp-"`` :type prefix: string, optional :return: file handle :rtype: handle The file is created in a temporary directory (commonly :file:`/tmp`). .. _`libc/sig-name`: .. idio:function:: libc/sig-name signum return the short signal name of `signum` :param signum: signal number :type signum: C/int :return: short signal name :rtype: string A short signal name would be ``QUIT`` or ``INT``. .. seealso:: :ref:`signal-name ` for long signal names. .. _`libc/signal-name`: .. idio:function:: libc/signal-name signum return the long signal name of `signum` :param signum: signal number :type signum: C/int :return: long signal name :rtype: string A long signal name would be ``SIGQUIT`` or ``SIGINT``. .. seealso:: :ref:`sig-name ` for short signal names. .. _`libc/sig-names`: .. idio:function:: libc/sig-names return a list of :samp:`({number} & {short name})` pairs of known signals :return: association list of signal pairs :rtype: list A short signal name would be ``QUIT`` or ``INT``. .. seealso:: :ref:`signal-names ` for long signal names. .. _`libc/signal-names`: .. idio:function:: libc/signal-names return a list of :samp:`({number} & {long name})` pairs of known signals :return: map of signal pairs :rtype: list A long signal name would be ``SIGQUIT`` or ``SIGINT``. .. seealso:: :ref:`sig-names ` for short signal names. .. _`libc/errno-name`: .. idio:function:: libc/errno-name errnum return the error name of `errnum` :param errnum: error number :type errnum: C/int :return: error name :rtype: string .. _`libc/errno-names`: .. idio:function:: libc/errno-names return a list of :samp:`({number} & {name})` pairs of known errno numbers :return: association list of errno pairs :rtype: list .. _`libc/rlimit-name`: .. idio:function:: libc/rlimit-name rlim return the string name of the :manpage:`getrlimit(2)` C macro :param rlim: the value of the macro :type rlim: C/int :return: a string :raises ^rt-parameter-type-error: .. _`libc/rlimit-names`: .. idio:function:: libc/rlimit-names return a list of :samp:`({number} & {name})` pairs of the :manpage:`getrlimit(2)` C macros each pair is the C value and string name of the macro :return: a list of pairs .. _`libc/open-flag-names`: .. idio:function:: libc/open-flag-names return a list of the :manpage:`open(2)` O_* flags :return: a list of flag names .. _`libc/make-poller`: .. idio:function:: libc/make-poller [args] Create a `poller` from `args` :param args: see below :type args: list :return: poller :rtype: C/pointer :raises ^rt-parameter-type-error: Each element of `args` should be a list of :samp:`({fdh} {eventmask} [{eventmask} ...])` where `fdh` can be an FD or an FD handle and `eventmask` can be a ``POLL*`` name or C/int derived from such names .. _`libc/poller-register`: .. idio:function:: libc/poller-register poller pollee Add `pollee` to `poller` :param poller: a poller from :ref:`libc/make-poller ` :type poller: C/pointer :param pollee: see below :type pollee: list :return: ``#`` :raises ^rt-parameter-type-error: `pollee` should be a list of :samp:`({fdh} {eventmask} [{eventmask} ...])` where `fdh` can be an FD or an FD handle and `eventmask` can be a ``POLL*`` name or C/int derived from such names .. _`libc/poller-deregister`: .. idio:function:: libc/poller-deregister poller fdh Remove `fdh` from `poller` :param poller: a poller from :ref:`libc/make-poller ` :type poller: C/pointer :param fdh: an FD or FD handle :type fdh: C/int or FD handle :return: ``#`` :raises ^rt-parameter-type-error: .. _`libc/poller-poll`: .. idio:function:: libc/poller-poll poller [timeout] Poll `poller` for `timeout` milliseconds :param poller: a poller from :ref:`libc/make-poller ` :type poller: C/pointer :param timeout: timeout in milliseconds, defaults to ``#n`` :type timeout: fixnum, bignum or C/int :return: list of :samp:`({fdh} {event})` tuples or ``#n`` :rtype: list :raises ^rt-parameter-type-error: :raises ^system-error: .. _`libc/poll-name`: .. idio:function:: libc/poll-name pollevent return the string name of the :manpage:`poll(2)` C macro :param pollevent: the value of the macro :type pollevent: C/int :return: a symbol :raises ^rt-parameter-type-error: :raises ^rt-hash-key-not-found-error: if `pollevent` not found .. _`libc/poll-names`: .. idio:function:: libc/poll-names return a list of :samp:`({number} & {name})` pairs of the :manpage:`poll(2)` C macros each pair is the C value and string name of the macro :return: a list of pairs .. _`libc/proc-subst-named-pipe-from`: .. idio:function:: libc/proc-subst-named-pipe-from return a (possibly named) pipe with pathnames for each end :return: see below :rtype: list On /dev/fd supporting systems the return value is the four element list: :samp:`({rfd}, {wfd}, {rname}, {wname})` Otherwise the return value is the five element list: :samp:`(#f, #f, {pipe-name}, {pipe-name}, {tmpdir})` .. _`libc/proc-subst-named-pipe-into`: .. idio:function:: libc/proc-subst-named-pipe-into return a (possibly named) pipe with pathnames for each end :return: see below :rtype: list On /dev/fd supporting systems the return value is the four element list: :samp:`({rfd}, {wfd}, {rname}, {wname})` Otherwise the return value is the five element list: :samp:`(#f, #f, {pipe-name}, {pipe-name}, {tmpdir})` .. _`poll predicates`: poll predicates ^^^^^^^^^^^^^^^ The `C/int` :lname:`C` macros, ``POLLIN``, ``POLLERR``, etc., are managed as bitmasks in a `C/short` in :manpage:`poll(2)`'s ``struct pollfd``. This is complicated because :lname:`Idio` doesn't use a `C/int` of 0 (zero) as `false` and the :lname:`C` bitwise operators, :ref:`C/& `, etc., only operate on `C/int` types. So a series of predicates exist which do the right thing, ``POLLIN?`` will test that the bit-field represented by the :lname:`C` macro, ``POLLIN`` is set in the `C/short` argument. When registering a file descriptor or file handle you can pass a list of `C/int` values which will be OR-ed together into a :lname:`C` ``short``. Later, the list of event results from :ref:`poller-poll ` will have an ``revents`` value which you can test with these predicates: .. code-block:: idio fh := open-input-file ... poller := libc/make-poller (list fh libc/POLLIN) r := libc/poller-poll poller 1000 for p in r { fdh := ph p revents := pht p (cond ((libc/POLLERR? revents) { libc/poller-deregister poller fdh }) ((libc/POLLIN? revents) { ... })) } .. include:: ../commit.rst