libc

The module libc exports a number of variables, many of which are operating system-specific and some are computed variables. Some of these are “built-in” in src/libc-wrap.c and some are dynamically generated for this platform in src/libc-api.c.

help libc will give a complete list of exported names.

Variables defined in module libc use libc-oriented types, commonly C/int and C portable type names such as libc/pid_t.

There are many places where it would be incredibly convenient to pass in a fixnum rather than the (correct) C base type but I’ve tried to resist. By and large, the values passed to C library functions should be the result of previous interactions with the C library. However, there are a few places where it’s allowed!

Common values for comparison purposes (read: one’s I’ve needed!), say, 0 (zero), have been created for use with C-specific comparators. Unfortunately, C’s rather easy way with integer promotion isn’t carried over into Idio and to avoid combinatorial explosion only like types can be compared. This means we have multiple zeroes. C/0i, a C/int, isn’t the same base type as C/0u, a C/uint, which isn’t the same type as, say, libc/0pid_t, a zero in the type of a libc/pid_t.

This requires that we can’t be as casual as we can in C:

Idio> C/> (libc/getpid) libc/0pid_t
#t
Idio> C/== C/0i (libc/kill (libc/getpid) C/0i)
#t

If no handy variable exists you can always create one:

Idio> C/integer-> -1 libc/pid_t
-1

although, as libc/pid_t is either directly referencing or part of a chain of references to a C base type then type->string can only return the base type.

Idio> x := C/integer-> -1 libc/pid_t
-1
Idio> type->string x
"C/int"

This is unfortunate as a pid_t is not an int on all systems (although it clearly is on this one). In other words, the output of type->string is not portable.

Stick to the C API!

Of course, in the particular case of system and standard library calls, when errors occur a ^system-error condition is raised such that the system/library call can often be presumed to have succeeded if you haven’t been thrown into a condition handler.

Not all C system or library calls conform to this practice.

Common libc Variables

libc/0pid_t

type:

libc/pid_t

value:

0 (zero)

libc/0gid_t

type:

libc/gid_t

value:

0 (zero)

From fcntl.h:

libc/FD_CLOEXEC

type:

C/int

libc/F_DUPFD

type:

C/int

libc/F_DUPFD_CLOEXEC

type:

C/int

Warning

Not all systems define F_DUPFD_CLOEXEC.

libc/F_GETFD

type:

C/int

libc/F_SETFD

type:

C/int

libc/F_GETFL

type:

C/int

libc/F_SETFL

type:

C/int

From limits.h:

libc/CHAR_MAX

type:

C/char

libc/SCHAR_MIN

type:

C/schar

libc/SCHAR_MAX

type:

C/schar

libc/UCHAR_MAX

type:

C/uchar

libc/INT_MIN

type:

C/int

libc/INT_MAX

type:

C/int

libc/UINT_MAX

type:

C/uint

libc/LONG_MIN

type:

C/long

libc/LONG_MAX

type:

C/long

libc/ULONG_MAX

type:

C/ulong

libc/LLONG_MIN

type:

C/longlong

libc/LLONG_MAX

type:

C/longlong

libc/ULLONG_MAX

type:

C/ulonglong

From signal.h:

libc/SIG_DFL

type:

C/pointer

libc/SIG_IGN

type:

C/pointer

From stdio.h:

libc/BUFSIZ

type:

C/int

libc/EOF

type:

C/int

libc/NULL

type:

C/pointer

Note

Not an integer!

From stdint.h:

libc/INTPTR_MIN

type:

libc/intptr_t

libc/INTPTR_MAX

type:

libc/intptr_t

libc/INTMAX_MIN

type:

libc/intmax_t

libc/INTMAX_MAX

type:

libc/intmax_t

libc/UINTMAX_MAX

type:

libc/uintmax_t

From sys/resource.h:

libc/RUSAGE_SELF

type:

C/int

libc/RUSAGE_CHILDREN

type:

C/int

Note

RUSAGE_BOTH and RUSAGE_THREAD are not generic and not currently available.

libc/RLIM_SAVED_MAX

type:

libc/rlim_t

Warning

Not all systems define RLIM_SAVED_MAX.

libc/RLIM_SAVED_CUR

type:

libc/rlim_t

Warning

Not all systems define RLIM_SAVED_CUR.

libc/RLIM_INFINITY

type:

libc/rlim_t

From sys/wait.h:

libc/WAIT_ANY

type:

libc/pid_t

libc/WNOHANG

type:

C/int

libc/WUNTRACED

type:

C/int

From termios.h:

libc/TCSADRAIN

type:

C/int

libc/TCSAFLUSH

type:

C/int

From unistd.h:

libc/PATH_MAX

type:

C/int

libc/STDIN_FILENO

type:

C/int

libc/STDOUT_FILENO

type:

C/int

libc/STDERR_FILENO

type:

C/int

libc/R_OK

type:

C/int

libc/W_OK

type:

C/int

libc/X_OK

type:

C/int

libc/F_OK

type:

C/int

libc/idio-uname

type:

C/pointer to a struct utsname from uname(3)

Idio> libc/idio-uname.sysname
"Linux"

Most of the elements are available as features to cond-expand:

(cond-expand
  (uname/sysname/SunOS ...)
  (uname/sysname/FreeBSD ...)
  (else ...))

libc/CLK_TCK

type:

C/long

This is the value of sysconf (_SC_CLK_TCK) which is useful for normalising the results for libc/times.

OS-dependent libc Variables

Here the set of names in various groups, signals, error, etc., are operating system-dependent.

Signal Names

Surprisingly, despite using the C macro value, say, SIGINT, in code there is no way to get the descriptive string “SIGINT” back out of the system. strsignal(3) provides the helpful string “Interrupt”.

We’re following in the footsteps of Bash’s support/signames.c.

libc/SIGINT libc/SIGTERM …

These are operating system-dependent.

For completeness a debug build will report on any signal numbers (between the lowest and highest defined) which do not have associated C definitions. These will be added as libc/SIGJUNKnnn.

The realtime signals, SIGRTMIN through to SIGRTMAX are not necessarily contiguous with regular signals.

You can convert a C/int signal number into either the short or long form names (eg, INT or SIGINT) with libc/sig-name and libc/signal-name.

You can get a list of all signal numbers with short or long signal names with libc/sig-names or libc/signal-names.

function sig-name sig

Return the short-form signal name, eg. “INT”

Param sig:

signal

Type sig:

C/int

Rtype:

string

function signal-name sig

Return the long-form signal name, eg. “SIGINT”

Param sig:

signal

Type sig:

C/int

Rtype:

string

function sig-names

Return a list of the signal number and the short-form signal names, eg. “INT”, pairs.

Rtype:

list (C/int & string)

((1 & "HUP") (2 & "INT") ...)
function signal-names

Return a list of the signal number and the long-form signal names, eg. “SIGINT”, pairs.

Rtype:

string

((1 & "SIGHUP") (2 & "SIGINT") ...)

Error Names

libc/EACCESS libc/EPERM …

These are operating system-dependent.

For completeness a debug build will report on any error numbers (between the lowest and highest defined) which do not have associated definitions. These will be added as libc/ERRUNKNOWNnnn.

You can convert a C/int error number into the error name with libc/errno-name.

You can get a list of all error numbers with error names with libc/errno-names.

libc/strerrno is the moral equivalent of strsignal(3) and is functionally identical to libc/errno-name.

C’s errno is accessible as a computed variable.

function errno-name errno

Return the error name, eg. “EPERM”

Param errno:

error number

Type errno:

C/int

Rtype:

string

function strerrno errno

Return the error name, eg. “EPERM”

Param errno:

error number

Type errno:

C/int

Rtype:

string

function errno-names

Return a list of the error number and the error name pairs.

Rtype:

list (C/int & string)

((1 & "EPERM") (2 & "ENOENT") ...)

RLIMIT Names

libc/RLIMIT_NOFILE …

These are operating system-dependent.

For completeness a debug build will report on any RLIMIT numbers (between the lowest and highest defined) which do not have associated definitions. These will be added as libc/RLIMIT_UNKNOWNnnn.

You can convert a C/int RLIMIT number into the RLIMIT name with libc/rlimit-name.

You can get a list of all RLIMIT numbers with names with libc/rlimit-names.

function rlimit-name rlim

Return the rlimit name, eg. “RLIMIT_NOFILE”

Param rlim:

rlimit identifier

Type rlim:

C/int

Rtype:

string

function rlimit-names

Return a list of the rlimit number and the rlimit name pairs.

Rtype:

list (C/int & string)

((0 & "RLIMIT_CPU") (1 & "RLIMIT_FSIZE") ...)

Computed libc Variables

libc/errno

type:

C/int

Note

There is no set method for this variable.

libc-api.c

Rather than document the (continually updated) .../ext/libc/src/libc-api.c this documentation is tied to the subset defined in src/build-bootstrap/libc-api.c.

The contents are, being platform-specific, not especially generic, however the intended portable interfaces are generic and we can describe those.

System and Library Functions

The ^rt-libc-format-error is usually picking up on the attempt to pass an Idio string with an embedded ASCII NUL into C.

function libc/access pathname mode

Call access(2).

Param pathname:

Type pathname:

string

Param mode:

R_OK etc.

Type mode:

C/int

Raises:

^rt-parameter-type-error ^rt-libc-format-error

Rtype:

boolean

function libc/chdir path

Call chdir(2).

Param path:

Type path:

string

Raises:

^rt-parameter-type-error ^rt-libc-format-error ^system-error

Rtype:

C/int

function libc/close fd

Call close(2).

Param fd:

file descriptor to close

Type fd:

C/int

Raises:

^rt-parameter-type-error ^system-error

Rtype:

C/int

function libc/dup oldfd

Call dup(2).

Param oldfd:

file descriptor to dup

Type oldfd:

C/int

Raises:

^rt-parameter-type-error ^system-error

Rtype:

C/int

function libc/dup2 oldfd newfd

Call dup2(2).

Param oldfd:

file descriptor to dup

Type oldfd:

C/int

Param newfd:

file descriptor to overwrite

Type newfd:

C/int

Raises:

^rt-parameter-type-error ^system-error

Rtype:

C/int

function libc/exit status

Call exit(3).

Param status:

Type status:

fixnum or C/int

Obviously, exit does not return!

The use of a fixnum here is a convenience for the likes of:

exit 1
function libc/fcntl fd cmd [arg]

Call fcntl(2).

Param fd:

file descriptor

Type fd:

C/int

Param cmd:

fcntl command

Type cmd:

C/int

Param arg:

(optional) fcntl command argument

Type arg:

varies

Raises:

^rt-parameter-type-error ^system-error

Rtype:

C/int

Supported commands include:

  • libc/F_DUPFD

    param arg:

    file descriptor to duplicate

    type arg:

    C/int

  • libc/F_DUPFD_CLOEXEC (if supported)

    param arg:

    file descriptor to duplicate

    type arg:

    C/int

  • libc/F_GETFD

  • libc/F_SETFD

    param arg:

    file descriptor flags

    type arg:

    C/int

  • libc/F_GETFL

  • libc/F_SETFL

    param arg:

    file status flags

    type arg:

    C/int

    See file status flags for what might be possible.

function libc/fork

Call fork(2).

Raises:

^system-error

Rtype:

libc/pid_t

function libc/getcwd

Call getcwd(3).

Raises:

^system-error

Rtype:

string

function libc/getpgpid

Call getpgpid(2).

Raises:

^system-error

Rtype:

libc/pid_t

function libc/getpgrp

Call getpgrp(2).

Raises:

^system-error

Rtype:

libc/pid_t

function libc/getpid

Call getpid(2).

Raises:

^system-error

Rtype:

libc/pid_t

function libc/getrlimit resource

Call getrlimit(2).

Param resource:

libc/RLIMIT_NOFILE etc.

Type resource:

C/int

Raises:

^rt-parameter-type-error ^system-error

Rtype:

C/pointer to a struct rlimit

function libc/getrusage who

Call getrusage(2).

Param who:

libc/RUSAGE_SELF etc.

Type who:

C/int

Raises:

^rt-parameter-type-error ^system-error

Rtype:

C/pointer to a struct rusage

function libc/getsid

Call getsid(2).

Raises:

^system-error

Rtype:

libc/pid_t

function libc/gettimeofday

Call gettimeofday(2).

Raises:

^system-error

Rtype:

C/pointer to a struct timeval

function libc/isatty

Call isatty(3).

Raises:

^rt-parameter-type-error ^system-error

Rtype:

C/int

Note

libc/isatty is strictly conforming to the library call model and raising a condition if the call fails.

Use the T? shell predicate to get a boolean result.

function libc/kill pid sig

Call kill(2).

Param pid:

process ID

Type pid:

libc/pid_t

Param sig:

signal

Type sig:

C/int

Raises:

^rt-parameter-type-error ^system-error

Rtype:

C/int

function libc/mkdir pathname mode

Call mkdir(2).

Param pathname:

Type pathname:

string

Param mode:

Type mode:

libc/mode_t

Raises:

^rt-parameter-type-error ^rt-libc-format-error ^system-error

Rtype:

C/int

Note

Few libc/mode_t values are defined. The libc/S_ISDIR etc. macros are defined.

function libc/mkdtemp template

Call mkdtemp(3).

Param template:

Type template:

string

Raises:

^rt-parameter-type-error ^rt-libc-format-error ^system-error

Return:

the unique directory name

Rtype:

string

function libc/mkstemp template

Call mkstemp(3).

This is complicated by mkstemp also returning an open file descriptor to the unique temporary file. In particular mkstemp modifies the (C) template which the caller can review. Here we generate a new Idio string from the C version of template.

Param template:

Type template:

string

Raises:

^rt-parameter-type-error ^rt-libc-format-error ^system-error

Return:

a list of the open file descriptor and the unique file name

Rtype:

list (C/int string)

function libc/pipe

Call pipe(2).

pipe takes an int[] which isn’t an Idio accessible type so there are two ancillary functions, pipe-reader and pipe-writer which take the result of this call and return the individual elements.

Raises:

^system-error

Rtype:

C/pointer

function libc/pipe-reader v
Param v:

the result of calling pipe

Type v:

C/pointer

Rtype:

C/int

function libc/pipe-writer v
Param v:

the result of calling pipe

Type v:

C/pointer

Rtype:

C/int

function libc/read fd [count]

Call read(2).

Param fd:

the file descriptor to read from

Type fd:

C/int

Param count:

(optional) the number of bytes to read

Type count:

fixnum or libc/size_t

Raises:

^rt-parameter-type-error ^system-error

Return:

a string of the bytes read or #<eof>

Rtype:

string or #<eof>

The use of a fixnum here is because you’re unlikely to have the appropriate libc/size_t as the result of a previous operation other than, possibly, using libc/BUFSIZ. So, on the rare occasion you need to supply a count, a fixnum is convenient.

function libc/rmdir pathname

Call rmdir(2).

Param pathname:

Type pathname:

string

Raises:

^rt-parameter-type-error ^rt-libc-format-error ^system-error

Rtype:

C/int

function libc/setpgpid pid pgid

Call setpgpid(2).

Param pid:

process ID to affect

Type pid:

C/int

Param pgid:

process group ID

Type pgid:

C/int

Raises:

^system-error

Rtype:

C/int

function libc/setrlimit resource rlim

Call setrlimit(2).

rlim should be the (modified) value returned from libc/getrlimit.

Param resource:

libc/RLIMIT_NOFILE etc.

Type resource:

C/int

Param rlim:

resource limit

Type rlim:

C/pointer to a struct rlimit

Raises:

^rt-parameter-type-error ^rt-parameter-value-error ^system-error

Rtype:

#<unspec>

By way of example, this code from lib/test.idio actively limits the number of open file descriptors to 256:

nofiles_lim := 256
C_nofiles_lim := C/integer-> nofiles_lim libc/rlim_t
rl := libc/getrlimit libc/RLIMIT_NOFILE
if (C/> rl.rlim_cur C_nofiles_lim) {
  rl.rlim_cur = C_nofiles_lim
  libc/setrlimit libc/RLIMIT_NOFILE rl
}

Notice that we have to convert our 256 into the correct C base type.

function libc/signal sig handler

Call signal(2).

Param sig:

signal

Type sig:

C/int

Param handler:

signal disposition

Type handler:

C/pointer

Raises:

^rt-parameter-type-error ^system-error

Return:

previous disposition

Rtype:

C/pointer

libc/SIG_DFL and libc/SIG_IGN are defined for use as handler, here.

function libc/sleep seconds

Call sleep(3).

Param seconds:

seconds to sleep

Type seconds:

fixnum or C/uint

Raises:

^rt-parameter-type-error

Return:

the number of seconds remaining if interrupted

Rtype:

C/uint

A fixnum, here, is very convenient.

function libc/stat pathname

Call stat(2).

Param pathname:

pathname to stat

Type pathname:

string

Raises:

^rt-parameter-type-error ^rt-libc-format-error ^system-error

Return:

the struct stat

Rtype:

C/pointer to a libc/struct stat

function libc/S_ISBLK mode

Call the C macro S_ISBLK.

Param mode:

mode to test

Type mode:

libc/mode_t

Rtype:

boolean

function libc/S_ISCHR mode

Call the C macro S_ISCHR.

Param mode:

mode to test

Type mode:

libc/mode_t

Rtype:

boolean

function libc/S_ISDIR mode

Call the C macro S_ISDIR.

Param mode:

mode to test

Type mode:

libc/mode_t

Rtype:

boolean

function libc/S_ISREG mode

Call the C macro S_ISREG.

Param mode:

mode to test

Type mode:

libc/mode_t

Rtype:

boolean

function libc/S_ISLNK mode

Call the C macro S_ISLNK.

Param mode:

mode to test

Type mode:

libc/mode_t

Rtype:

boolean

function libc/S_ISFIFO mode

Call the C macro S_ISFIFO.

Param mode:

mode to test

Type mode:

libc/mode_t

Rtype:

boolean

function libc/S_ISSOCK mode

Call the C macro S_ISSOCK.

Param mode:

mode to test

Type mode:

libc/mode_t

Rtype:

boolean

function libc/strerror errnum

Call strerror(3).

Param errnum:

errnum to decode

Type errnum:

C/int

Raises:

^rt-parameter-type-error ^system-error

Return:

the error message

Rtype:

string

function libc/strsignal sig

Call strsignal(3).

Param sig:

the signal number to decode

Type sig:

C/int

Raises:

^rt-parameter-type-error

Return:

the strsignal buf

Rtype:

string (see note)

Note

On some systems, SunOS, strsignal(3) will return NULL, eg. for -1. Here we return #n.

function libc/tcgetattr fd

Call tcgetattr(3).

Param fd:

the file descriptor

Type fd:

C/int

Raises:

^rt-parameter-type-error ^system-error

Return:

the termios structure

Rtype:

C/pointer to a libc/struct termios

function libc/tcgetpgrp fd

Call tcgetpgrp(3).

Param fd:

the file descriptor

Type fd:

C/int

Raises:

^rt-parameter-type-error ^system-error

Return:

process ID

Rtype:

libc/pid_t

function libc/tcsetattr fd options termios

Call tcsetattr(3).

Param fd:

the file descriptor

Type fd:

C/int

Param options:

options

Type options:

C/int

Param termios:

the termios structure

Type termios:

C/pointer to a libc/struct termios

Raises:

^rt-parameter-type-error ^system-error

Return:

the termios structure

Rtype:

C/pointer to a libc/struct termios

The following options are defined: libc/TCSADRAIN and libc/TCSAFLUSH.

See libc/tcgetattr for obtaining a struct termios.

function libc/tcsetpgrp fd pgrp

Call tcsetpgrp(3).

Param fd:

the file descriptor

Type fd:

C/int

Param pgrp:

the process group ID

Type pgrp:

libc/pid_t

Raises:

^rt-parameter-type-error ^system-error

Rtype:

C/int

function libc/times

Call times(3).

Raises:

^system-error

Rtype:

list of (libc/clock_t C/pointer to a libc/struct tms)

See also libc/CLK_TCK.

function libc/uname

Call uname(3).

Raises:

^system-error

Rtype:

C/pointer to a libc/struct utsname

See also libc/idio-uname which has already called this function.

function libc/waitpid pid options

Call waitpid(2).

Param pid:

process ID

Type pid:

libc/pid_t

Param options:

Type options:

C/int

Raises:

^rt-parameter-type-error ^system-error

Return:

the process and status

Rtype:

list of (libc/pid_t C/pointer)

libc/WAIT_ANY is defined as -1 in place of pid.

The following options are defined: libc/WNOHANG libc/WUNTRACED.

The returned C/pointer is a C int *. See libc/WIFEXITED, libc/WEXITSTATUS, libc/WIFSIGNALLED, libc/WTERMSIG, libc/WIFSTOPPED for functions to manipulate this value.

function libc/WIFEXITED status

Call the C macro WIFEXITED.

Param status:

status

Type status:

C/pointer

Rtype:

boolean

function libc/WEXITSTATUS status

Call the C macro WEXITSTATUS.

Param status:

status

Type status:

C/pointer

Rtype:

C/int

function libc/WIFSIGNALLED status

Call the C macro WIFSIGNALLED.

Param status:

status

Type status:

C/pointer

Rtype:

boolean

function libc/WTERMSIG status

Call the C macro WTERMSIG.

Param status:

status

Type status:

C/pointer

Rtype:

C/int

function libc/WIFSTOPPED status

Call the C macro WIFSTOPPED.

Param status:

status

Type status:

C/pointer

Rtype:

boolean

function libc/write fd str

Call write(2).

Param fd:

the file descriptor to write to

Type fd:

C/int

Param str:

the string to write

Type str:

string

Raises:

^rt-parameter-type-error ^system-error

Return:

the number of bytes written

Rtype:

libc/ssize_t

File Status Flags

File status flags are a bit inconsistent across platforms so the results may not be portable. But you knew that anyway, right?

File access modes are available on all platforms:

O_RDONLY

O_WRONLY

O_RDWR

Linux notes a distinction between file creation flags (the first few in the table below) and further file status flags in addition to the creation flags.

I’m working on the basis that the manual pages speak the intent of the platform even if the header files are a little more generous. Ostensibly, Mac OS, for example, doesn’t use any of the SYNC flags yet they are defined in the header files.

Together with flags from other systems we have the following table:

flag

Linux

FreeBSD

SunOS

Mac OS

notes

O_CLOEXEC

Y

Y

Y

Y

creation

O_CREAT

Y

Y

Y

Y

creation

O_DIRECTORY

Y

Y

-

-

creation

O_EXCL

Y

Y

Y

Y

creation

O_NOCTTY

Y

i

Y

-

creation

O_NOFOLLOW

Y

Y

Y

Y

creation

O_TRUNC

Y

Y

Y

Y

creation

O_APPEND

Y

Y

Y

Y

O_ASYNC

Y

-

Y

-

O_DIRECT

Y

Y

Y

-

O_DSYNC

Y

Y

Y

-

O_FSYNC

Y

Y

-

Y

synonym for O_SYNC

O_EXLOCK

-

Y

-

Y

O_LARGEFILE

Y

-

Y

-

O_NONBLOCK

Y

Y

Y

Y

O_NDELAY

Y

Y

Y

Y

synonym for O_NONBLOCK

O_PATH

Y

-

-

-

O_SHLOCK

-

Y

-

Y

O_SYNC

Y

Y

Y

-

i – is ignored on FreeBSD

(I’ve ignored flags which appear to be unique to a platform.)

So, pretty spotty. Once a file is open, most flags are ignored when you come to (try to) change then with fnctl(2). Linux notes:

File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags.

Other systems have varying support as well.

I guess, like error numbers, signal numbers etc., we expose what the platform exposes.

POSIX regex

The POSIX regex(3) functions are defined in src/posix-regex.c and the primitives are available to all which, together with the routines in lib/posix-regex.idio, give rise to the fundamental to pattern matching in Idio.

function libc/regcomp rx [flags]

Call regcomp(3).

Of course the user can’t pass in a regex_t * so this code will create one and return it.

Param rx:

the regular expression

Type rx:

string

Param flags:

(optional) flags

Type flags:

symbols

Raises:

^rt-parameter-type-error ^rt-parameter-value-error ^rt-regex-error

Return:

the compiled regular expression

Rtype:

C/pointer

The flags are: REG_EXTENDED, REG_ICASE, REG_NOSUB (ignored) and REG_NEWLINE.

Like other systems, this code defaults to REG_EXTENDED so there is an extra REG_BASIC flag to disable REG_EXTENDED.

function libc/regexec rx str [flags]

Call regexec(3).

Param rx:

the compiled regular expression

Type rx:

C/pointer

Param str:

the string to match against

Type str:

string

Param flags:

(optional) flags

Type flags:

symbols

Raises:

^rt-parameter-type-error ^rt-parameter-value-error

Return:

an array of matching subexpressions or #f if no match

The flags are: REG_NOTBOL, REG_NOTEOL and REG_STARTEND (if supported).

On a successful match an array of the subexpressions in rx is returned with the first (zero-th) being the entire matched string.

If a subexpression in rx matched the corresponding array element will be the matched string.

If a subexpression in rx did not match the corresponding array element will be #f.

The POSIX functions regerror(3) and regfree(3) are automatically invoked where required.

lib/posix-regex.idio defines two shell-like pattern matching functions (technically, templates).

function regex-case str *clauses*

regex-case works like case in that it takes a sequence of clauses where the first element of each clause is a regular expression to be compared to str in turn.

If a regular expression matches then the clauses remaining expressions are run and the final value is the value regex-case returns.

An else clause is permitted.

The array returned from regexec is available in the remaining expressions as the variable r.

The code is complicated slightly by endeavouring to remember the (otherwise) interim compiled regular expressions in case this expression is run in a loop.

(regex-case libc/idio-uname.release
  ("^([[:digit:]]\\.[[:digit:]]+)" {
     printf "this is a %s kernel\n" r.1           ; this is a 5.11 kernel
   }))

regex-case is too visually complex for most of the pattern matching that I do, usually with Bash’s case statement. For those circumstances we can put a wrapper around regex-case and further use regex-case to pick out * and ? and replace them with .* and . respectively giving us:

function pattern-case str *clauses*
(pattern-case libc/idio-uname.sysname
  ("SunOS" {
     printf "this is Solaris\n"
   })
  ("*BSD" {
     printf "this is a BSD\n"
   })
  (else {
     printf "this isn't Solaris or a BSD\n"
   }))

Structures and Accessors

libc/struct rlimit

rlim_cur
Type:

libc/rlim_t

rlim_max
Type:

libc/rlim_t

function libc/struct-rlimit-ref rlimit member
Param rlimit:

Type rlimit:

C/pointer to a struct rlimit

Param member:

structure member name

Type member:

symbol

Raises:

^rt-parameter-type-error ^rt-parameter-value-error

Rtype:

libc/rlim_t

function libc/struct-rlimit-set! rlimit member val
Param rlimit:

Type rlimit:

C/pointer to a struct rlimit

Param member:

structure member name

Type member:

symbol

Param val:

Type val:

libc/rlim_t

Raises:

^rt-parameter-type-error ^rt-parameter-value-error

Rtype:

#<unspec>

libc/struct rusage

ru_utime
Type:

C/pointer to a struct timeval

ru_stime
Type:

C/pointer to a struct timeval

Note

Other members are not available yet – and are operating system-dependent.

function libc/struct-rusage-ref rusage member
Param rusage:

Type rusage:

C/pointer to a struct rusage

Param member:

structure member name

Type member:

symbol

Raises:

^rt-parameter-type-error ^rt-parameter-value-error

Rtype:

member-specific

Note

There is no libc/struct-rusage-set! function.

libc/struct stat

Most of the fields are as you would expect except modern timestamps are different.

st_dev
Type:

libc/dev_t

st_ino
Type:

libc/ino_t

Type:

libc/nlink_t

st_mode
Type:

libc/mode_t

st_uid
Type:

libc/uid_t

st_gid
Type:

libc/gid_t

st_rdev
Type:

libc/dev_t

st_size
Type:

libc/off_t

st_blksize
Type:

libc/blksize_t

st_blocks
Type:

libc/blkcnt_t

In the before-times, a Unix filesystem timestamp was a time_t but these have all been migrated to struct timespec. The rather useful side-effect of using a struct timespec is that the tv_sec member is a time_t (and now a 64-bit value) so by some judicious #defines they could maintain the illusion of the traditional interface whilst allowing progressive code to access the finer-grained value.

#defines aren’t visible to the code-generating system so these old-ways have been manually added.

There’s another slight complication in that most operating systems call the new struct timepsec field, say, st_atim – without the trailing e. However, Mac OS calls the fields an, arguably better, st_atimespec.

I’ve normalised to st_atim on all systems for better or for worse.

st_atim
Type:

C/pointer to a libc/struct timespec

st_atime
Type:

libc/time_t

st_mtim
Type:

C/pointer to a libc/struct timespec

st_mtime
Type:

libc/time_t

st_ctim
Type:

C/pointer to a libc/struct timespec

st_ctime
Type:

libc/time_t

Note

Other members are not available yet – and are operating system-dependent.

function libc/struct-stat-ref stat member
Param stat:

Type stat:

C/pointer to a struct stat

Param member:

structure member name

Type member:

symbol

Raises:

^rt-parameter-type-error ^rt-parameter-value-error

Rtype:

member-specific

Note

There is no libc/struct-stat-set! function.

libc/struct termios

c_iflag
Type:

libc/tcflag_t

c_oflag
Type:

libc/tcflag_t

c_cflag
Type:

libc/tcflag_t

c_lflag
Type:

libc/tcflag_t

c_cc
Type:

libc/cc_t *

Technically, the type is cc_t[].

The following members are non-portable and cannot be referenced or set at the moment.

c_line
Type:

libc/cc_t

Linux only.

c_ispeed
Type:

libc/speed_t

Not in SunOS.

c_ospeed
Type:

libc/speed_t

Not in SunOS.

function libc/struct-termios-ref termios member
Param termios:

Type termios:

C/pointer to a struct termios

Param member:

structure member name

Type member:

symbol

Raises:

^rt-parameter-type-error ^rt-parameter-value-error

Rtype:

member-specific

function libc/struct-termios-set! termios member val
Param termios:

Type termios:

C/pointer to a struct termios

Param member:

structure member name

Type member:

symbol

Param val:

Type val:

as appropriate

Raises:

^rt-parameter-type-error ^rt-parameter-value-error

Rtype:

#<unspec>

libc/struct timespec

tv_sec
Type:

libc/time_t

tv_nsec
Type:

C/long

Note

Some systems define tv_nsec as a __syscall_slong_t which appears to be a long.

function libc/struct-timespec-ref timespec member
Param timespec:

Type timespec:

C/pointer to a struct timespec

Param member:

structure member name

Type member:

symbol

Raises:

^rt-parameter-type-error ^rt-parameter-value-error

Rtype:

member-specific

function libc/struct-timespec-set! timespec member val
Param timespec:

Type timespec:

C/pointer to a struct timespec

Param member:

structure member name

Type member:

symbol

Param val:

Type val:

libc/time_t or libc/suseconds_t as appropriate

Raises:

^rt-parameter-type-error ^rt-parameter-value-error

Rtype:

#<unspec>

libc/struct timeval

tv_sec
Type:

libc/time_t

tv_usec
Type:

libc/suseconds_t

Note

Not all systems define a suseconds_t so ext/libc/src/lib-api.c typedefs either __suseconds_t or long.

function libc/struct-timeval-ref timeval member
Param timeval:

Type timeval:

C/pointer to a struct timeval

Param member:

structure member name

Type member:

symbol

Raises:

^rt-parameter-type-error ^rt-parameter-value-error

Rtype:

member-specific

function libc/struct-timeval-set! timeval member val
Param timeval:

Type timeval:

C/pointer to a struct timeval

Param member:

structure member name

Type member:

symbol

Param val:

Type val:

libc/time_t or libc/suseconds_t as appropriate

Raises:

^rt-parameter-type-error ^rt-parameter-value-error

Rtype:

#<unspec>

function libc/add-struct-timeval tv1 tv2
Param tv1:

Type tv1:

C/pointer to a struct timeval

Param tv2:

Type tv2:

C/pointer to a struct timeval

Rtype:

C/pointer to a struct timeval

function libc/subtract-struct-timeval tv1 tv2
Param tv1:

Type tv1:

C/pointer to a struct timeval

Param tv2:

Type tv2:

C/pointer to a struct timeval

Rtype:

C/pointer to a struct timeval

function libc/struct-timeval-as-string timeval
Param timeval:

Type timeval:

C/pointer to a struct timeval

Raises:

^rt-parameter-value-error

Rtype:

string

Returns the common %ld.%06ld format – where the precision, 6, may be overridden by %format.

libc/struct tms

tms_utime
Type:

libc/clock_t

tms_stime
Type:

libc/clock_t

tms_cutime
Type:

libc/clock_t

tms_cstime
Type:

libc/clock_t

Note

Other members are not available yet – and are operating system-dependent.

function libc/struct-tms-ref tms member
Param tms:

Type tms:

C/pointer to a struct tms

Param member:

structure member name

Type member:

symbol

Raises:

^rt-parameter-type-error ^rt-parameter-value-error

Rtype:

member-specific

Note

There is no libc/struct-tms-set! function.

libc/struct utsname

sysname
Type:

string

nodename
Type:

string

release
Type:

string

version
Type:

string

machine
Type:

string

Note

Other members are not available yet – and are operating system-dependent.

function libc/struct-utsname-ref utsname member
Param utsname:

Type utsname:

C/pointer to a struct utsname

Param member:

structure member name

Type member:

symbol

Raises:

^rt-parameter-type-error ^rt-parameter-value-error

Rtype:

member-specific

Note

There is no libc/struct-utsname-set! function.

Last built at 2025-10-04T06:11:05Z+0000 from 463152b (dev)