posixc
--background_POSIX--
Notes
On AROS standardized C interfaces are implemented with a few shared libraries. A distinction is made between a standard ANSI-C/ISO-C part and a POSIX emulation layer. Here the POSIX part is documented. The posixc.library is a shared library that implements (part of) the C interface for POSIX.1-2008 on AROS and the standard document is used as guideline for this implementation. Purpose of this library is to implement a POSIX compliant compatibility layer. Currently no full implementation of the POSIX layer is provided but enough to port a lot of POSIX compliant or LINUX code over to AROS. As this library has overhead in implementation 'real' AROS/Amiga programs should not depend on this library. Also some non-standard or legacy POSIX functions are provided by the library. If possible they are put in the static link library so the functions can be removed in the future without breaking backwards compatibility. When porting code it is then preferred to patch the source code to use the POSIX.1-2008 version of files or provide a local version of some of the functions. The include files provided for the POSIX code implement a proper separation of the include files. The includes should only define the prototypes, constants etc. as defined by the standard. This means includes like proto/posixc.h should not be included in the standard POSIX include files. Developers improving or extending these libraries should keep this in mind. In order to use the posixc.library programs need to properly initialize the library using the __posixc_nixmain() function. It is assumed that this is taken care of by the startup code provided by the compiler.
See also
stdc/--background_C99--
__get_default_file()
Synopsis
int __get_default_file( int file_descriptor, long * file_handle)
Function
Gets dos.library file handle associated with a given file descriptor.
Inputs
file_descriptor - the File Descriptor you wish to obtain the associated
file handle for.
file_handle - Pointer to store the associated file handle.
Result
!=0 on error, 0 on success.
Notes
This function is not a part of the ISO C standard, it comes from clib2 project and was implemented to make porting of abc-shell easier. Function should not be used in new code.
__path_a2u()
Synopsis
const char *__path_a2u( const char *apath)
Function
Translates an AmigaDOS-style path into an unix one.
Inputs
apath - AmigaDOS-style path to translate into an unix-style equivalent.
Result
A pointer to a string containing the unix-style path, or NULL in case of error. The pointer is valid only until next call to this function, so if you need to call this function recursively, you must save the string pointed to by the pointer before calling this function again.
Notes
This function is for private usage by system code. Do not use it elsewhere.
__path_u2a()
Synopsis
const char *__path_u2a( const char *upath)
Function
Translates a unix-style path into an AmigaDOS one.
Inputs
upath - Unix-style path to translate into an AmigaDOS-style equivalent.
Result
A pointer to a string containing the AmigaDOS-style path, or NULL in case of error. The pointer is valid only until next call to this function, so if you need to call this function recursively, you must save the string pointed to by the pointer before calling this function again.
Notes
This function is for private usage by system code. Do not use it elsewhere.
__posixc_assert()
Synopsis
void __posixc_assert( const char * expr, const char * file, unsigned int line)
Function
This is a function that is used for implementation of the C99 assert() function.
Inputs
expr - The expression to evaluate. The type of the expression does
not matter, only if its zero/NULL or not.
file - Name of the source file.
line - Line number of assert() call.
Result
The function doesn't return.
Notes
Different versions of this function are available. This function is used when a program is using posixc.library.
_exit()
Synopsis
void _exit( int code)
Function
Terminates the calling process immediately.
Inputs
code - exit status.
Result
Does not return.
Notes
stdc.library provides _exit() only as a weak alias of _Exit(), which longjmps to the exit jmp_buf registered in the CALLER'S per-opener StdCBase. A vfork() child runs as the parent task pretending to be the child: __vfork intercepts the exit jmp_buf in the StdCBase instance posixc.library holds, but a program's own _exit() call resolves through the PROGRAM'S StdCBase instance, sails past the interception, and executes the real program teardown in the borrowed context - destroying the parent. This strong implementation routes a pretend-child's _exit() to the vfork exit jmp_buf; outside vfork it is equivalent to _Exit().
access()
Synopsis
int access( const char *path, int mode)
Function
Check access permissions of a file or pathname
Inputs
path - the path of the file being checked
mode - the bitwise inclusive OR of the access permissions
to be checked:
W_OK - for write permission
R_OK - for read permissions
X_OK - for execute permission
F_OK - Just to see whether the file exists
Result
If path cannot be found or if any of the desired access modes would not be granted, then a -1 value is returned; otherwise a 0 value is returned.
See also
alphasort()
Synopsis
int alphasort( const struct dirent **a, const struct dirent **b )
Function
Support function for scandir().
See also
alphasort64()
Synopsis
int alphasort64( const struct dirent64 **a, const struct dirent64 **b )
Function
Support function for scandir64().
See also
asctime_r()
Synopsis
char * asctime_r( const struct tm * tm, char * buf)
Function
The asctime_r() function converts the broken-down time value tm into
a string with this format:
"Wed Jun 30 21:49:08 1993\n"
It is the reentrant variant of asctime(): the result is stored in the
caller-supplied buffer rather than in a shared static buffer.
Inputs
tm - The broken down time buf - Buffer of at least 26 characters to store the string in
Result
The pointer passed in buf, containing the converted time (with a trailing newline), or NULL if tm does not describe a valid time.
Example
time_t tt; struct tm tm; char str[26]; // Get time time (&tt); // Break time up localtime_r (&tt, &tm); // Convert to string asctime_r (&tm, str);
basename()
Synopsis
char *basename( char *filename)
Function
Returns the part after the latest '/' of a path. Trailing '/' are not counted as part of the path.
Inputs
filename - Path which should be split.
Result
Rightmost part of the path.
See also
cfgetispeed()
Synopsis
speed_t cfgetispeed( const struct termios *__termios_p)
Function
Read the input speed code in a terminal-attribute object.
Inputs
__termios_p - Readable terminal-attribute object whose
input speed has been initialized.
Result
The stored input speed code. A NULL pointer returns B0. The function does not change errno; B0 is not an error indicator.
Notes
Include <termios.h>. This function accesses the supplied object only; it performs no terminal or device I/O.
Bugs
tcgetattr() does not initialize the stored speeds. Set the input speed with cfsetispeed() before reading it; a successful tcgetattr() call alone is insufficient.
See also
cfgetospeed()
Synopsis
speed_t cfgetospeed( const struct termios *__termios_p)
Function
Read the output speed code in a terminal-attribute object.
Inputs
__termios_p - Readable terminal-attribute object whose
output speed has been initialized.
Result
The stored output speed code. A NULL pointer returns B0. The function does not change errno; B0 is not an error indicator.
Notes
Include <termios.h>. This function accesses the supplied object only; it performs no terminal or device I/O.
Bugs
tcgetattr() does not initialize the stored speeds. Set the output speed with cfsetospeed() before reading it; a successful tcgetattr() call alone is insufficient.
See also
cfsetispeed()
Synopsis
int cfsetispeed( struct termios *__termios_p, speed_t speed)
Function
Store the input speed code in a terminal-attribute object.
Inputs
__termios_p - Writable terminal-attribute object.
speed - Speed code, normally a B-prefixed constant from
<termios.h>, such as B9600; not a baud count.
Result
0 after storing speed. Returns -1 and sets errno to EINVAL if __termios_p is NULL. Success does not clear errno.
Notes
Include <termios.h>. This function accesses the supplied object only; it performs no terminal or device I/O. Only the input speed is changed.
Bugs
The implementation accepts any speed_t value without checking whether it names a supported rate. tcsetattr() does not apply the stored speed to the terminal. B0 is stored literally; the input speed is not resolved to the output speed.
See also
cfsetospeed()
Synopsis
int cfsetospeed( struct termios *__termios_p, speed_t speed)
Function
Store the output speed code in a terminal-attribute object.
Inputs
__termios_p - Writable terminal-attribute object.
speed - Speed code, normally a B-prefixed constant from
<termios.h>, such as B9600; not a baud count.
Result
0 after storing speed. Returns -1 and sets errno to EINVAL if __termios_p is NULL. Success does not clear errno.
Notes
Include <termios.h>. This function accesses the supplied object only; it performs no terminal or device I/O. Only the output speed is changed.
Bugs
The implementation accepts any speed_t value without checking whether it names a supported rate. tcsetattr() does not apply the stored speed to the terminal.
See also
chdir()
Synopsis
int chdir( const char *path )
Function
Change the current working directory to the one specified by path.
Inputs
path - Path of the directory to change to.
Result
If the current directory was changed successfully, zero is returned. Otherwise, -1 is returned and errno set appropriately.
Notes
At program exit, the current working directory will be changed back to the one that was current when the program first started. If you do not desire this behavior, use dos.library/CurrentDir() instead. The path given to chdir can be translated so that getcwd gives back a string that is not the same but points to the same directory. For example, assigns are replaced by the path where the assign points to and device names (like DH0:) are replaced with the volume name (e.g. Workbench:).
chmod()
Synopsis
int chmod( const char *path, mode_t mode)
Function
Change permission bits of a specified file.
Inputs
path - Pathname of the file
mode - Bit mask created by ORing zero or more of the following
permission bit masks:
S_ISUID - set user id on execution
S_ISGID - set group id on execution
S_ISVTX - sticky bit (restricted deletion flag)
S_IRUSR - allow owner to read
S_IWUSR - allow owner to write
S_IXUSR - allow owner to execute/search directory
S_IRGRP - allow group to read
S_IWGRP - allow group to write
S_IXGRP - allow group to execute/search directory
S_IROTH - allow others to read
S_IWOTH - allow others to write
S_IXOTH - allow others to execute/search directory
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
Bugs
S_ISUID and S_ISGID are silently ignored.
See also
chown()
Synopsis
int chown( const char *path, uid_t owner, gid_t group)
Function
Change the user and group ownership of a file.
Inputs
path - the path to file owner - new owner ID group - new group ID
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
Notes
This implementation was done by looking at Olaf 'Olsen' Barthels clib2.
clearerr()
Synopsis
void clearerr( FILE * stream)
Function
Clear EOF and error flag in a stream. You must call this for example after you have read the file until EOF, then appended something to it and want to continue reading.
Inputs
stream - The stream to be reset.
Result
None.
See also
clock_gettime()
Synopsis
int clock_gettime( clockid_t clk_id, struct timespec *tp)
Function
retrieve the time of the specified clock clk_id.
Inputs
clk_id - identifier of the particular clock on which to act
CLOCK_REALTIME
System-wide real-time clock. Setting this clock requires appropriate privileges.
CLOCK_MONOTONIC
Clock that cannot be set and represents monotonic time since some unspecified starting point.
CLOCK_PROCESS_CPUTIME_ID
High-resolution per-process timer from the CPU.
CLOCK_THREAD_CPUTIME_ID
Thread-specific CPU-time clock.
tp - structure to hold the retrieved time value
Result
0 on success, -1 on error
Notes
Currently at most a resolution of milliseconds is supported.
close()
Synopsis
int close( int fd)
Function
Closes an open file. If this is the last file descriptor associated with this file, then all allocated resources are freed, too.
Inputs
fd - The result of a successful open()
Result
-1 for error or zero on success.
Notes
This function must not be used in a shared library or in a threaded application.
closedir()
Synopsis
int closedir( DIR *dir)
Function
Closes a directory
Inputs
dir - the directory stream pointing to the directory being closed
Result
The closedir() function returns 0 on success or -1 on failure.
creat()
Synopsis
int creat( const char * pathname, int mode)
Function
Creates a file with the specified mode and name.
Inputs
pathname - Path and filename of the file you want to open. mode - The access flags.
Result
-1 for error or a file descriptor for use with write().
Notes
If the filesystem doesn't allow to specify different access modes for users, groups and others, then the user modes are used. This is the same as open (pathname, O_CREAT|O_WRONLY|O_TRUNC, mode); This function must not be used in a shared library or in a threaded application.
See also
creat64()
Synopsis
int creat64( const char * pathname, int mode)
Function
Creates a file with the specified mode and name.
Inputs
pathname - Path and filename of the file you want to open. mode - The access flags.
Result
-1 for error or a file descriptor for use with write().
Notes
If the filesystem doesn't allow to specify different access modes for users, groups and others, then the user modes are used. This is the same as open (pathname, O_CREAT|O_WRONLY|O_TRUNC, mode); This function must not be used in a shared library or in a threaded application.
ctime_r()
Synopsis
char * ctime_r( const time_t * tt, char * buf)
Function
The ctime_r() function converts the time value tt into a string with
this format:
"Wed Jun 30 21:49:08 1993\n"
It is the reentrant variant of ctime(): the result is stored in the
caller-supplied buffer rather than in a shared static buffer. It is
equivalent to asctime_r(localtime_r(tt, &tm), buf).
Inputs
tt - Convert this time. buf - Buffer of at least 26 characters to store the string in
Result
The pointer passed in buf, containing the converted time (with a trailing newline), or NULL on failure.
Example
time_t tt; char str[26]; // Get time time (&tt); // Convert to string ctime_r (&tt, str);
dirfd()
Synopsis
int dirfd( DIR *dir)
Function
get directory stream file descriptor
Inputs
dir - directory stream dir.
Result
on error -1 is returned.
Notes
This descriptor is the one used internally by the directory stream. As a result, it is only useful for functions which do not depend on or alter the file position, such as fstat(2) and fchdir(2). It will be automatically closed when closedir(3) is called.
See also
dirname()
Synopsis
char *dirname( char *filename)
Function
Returns the string up to the latest '/'.
Inputs
filename - Path which should be split
Result
Directory part of the path.
See also
dprintf()
Synopsis
int dprintf( int fd, const char * restrict format, ...)
Function
Format output according to format and write it to the file descriptor fd. Equivalent to fprintf() but operating on a POSIX file descriptor rather than a FILE stream.
Inputs
fd - the file descriptor to write to. format - printf()-style format string. ... - the arguments consumed by the format string.
Result
The number of bytes written, or a negative value on error.
See also
drand48()
Synopsis
double drand48( void)
Function
Advance the shared 48-bit pseudo-random state and return a fraction derived from the new state.
Inputs
None.
Result
The new state divided by 2^48, in the range [0.0, 1.0). See BUGS for an arithmetic defect that invalidates this result contract.
Notes
Include <stdlib.h>. The default recurrence is X = (0x5deece66d * X + 11) modulo 2^48. lcong48() changes the multiplier and increment used by this function; srand48() and seed48() restore their defaults. This generator is not suitable for cryptographic use. The initial state is 0x1234abcd330e. srand48(), seed48() and lcong48() replace this state; lrand48() and mrand48() advance it. Calls using this shared state or changing the generator parameters require external synchronization.
Bugs
The shared generator can overflow signed int arithmetic on targets with 32-bit int, including on the first call from the default state. Its sequence and return value are not reliable under standard C overflow semantics.
dup()
Synopsis
int dup( int oldfd )
Function
Duplicates a file descriptor. The object referenced by the descriptor does not distinguish between oldd and newd in any way. Thus if newd and oldd are duplicate references to an open file, read(), write() and lseek() calls all move a single pointer into the file, and append mode, non-blocking I/O and asynchronous I/O options are shared between the references. If a separate pointer into the file is desired, a different object reference to the file must be obtained by issuing an additional open(2) call. The close-on-exec flag on the new file descriptor is unset.
Inputs
oldfd - The file descriptor to be duplicated
Result
-1 for error or the new descriptor. The new descriptor returned by the call is the lowest numbered descriptor currently not in use by the process.
Notes
This function must not be used in a shared library or in a threaded application.
dup2()
Synopsis
int dup2( int oldfd, int newfd )
Function
Duplicates a file descriptor. The object referenced by the descriptor does not distinguish between oldfd and newfd in any way. Thus if newfd and oldfd are duplicate references to an open file, read(), write() and lseek() calls all move a single pointer into the file, and append mode, non-blocking I/O and asynchronous I/O options are shared between the references. If a separate pointer into the file is desired, a different object reference to the file must be obtained by issuing an additional open(2) call. The close-on-exec flag on the new file descriptor is unset. If oldfd is valid and has the same integer value as newfd, nothing is done, and newfd is returned unchanged. If newfd is already valid when this function is called, its old descriptor is deallocated before this function returns. This function fails gracefully if oldfd is invalid.
Inputs
oldfd - The file descriptor to be duplicated
newfd - The value of the new descriptor we want the old one to be
duplicated in
Result
-1 for error or newfd on success
Notes
This function must not be used in a shared library or in a threaded application.
endgrent()
Synopsis
void endgrent( void)
Function
Operates on the group database via netinfo.device interface, Providing a convenient unix-compatible interface to the group unit of the netinfo.device.
See also
endpwent()
Synopsis
void endpwent( void)
Function
Operates on the user database via netinfo.device interface, Providing a convenient unix-compatible interface to the password unit of the netinfo.device.
See also
erand48()
Synopsis
double erand48( unsigned short xseed[3])
Function
Advance a caller-supplied 48-bit pseudo-random state and return a fraction derived from the new state.
Inputs
xseed - Writable array of three initialized unsigned short
values, from least to most significant 16-bit word.
The array must remain valid for the call; NULL is
not accepted. All three words are updated in place.
Result
The updated state divided by 2^48, in the range [0.0, 1.0). See BUGS for an arithmetic defect that invalidates this result contract.
Notes
Include <stdlib.h>. The default recurrence is X = (0x5deece66d * X + 11) modulo 2^48. lcong48() changes the multiplier and increment used by this function; srand48() and seed48() restore their defaults. This generator is not suitable for cryptographic use. The function retains no pointer to xseed. Reuse the updated array to continue a sequence. A separate array keeps its state independent of drand48(), but does not isolate it from changes to the shared multiplier and increment. Synchronize access to a shared array and exclude concurrent changes to those parameters.
Bugs
The shared generator can overflow signed int arithmetic on targets with 32-bit int, including on the first call from the default state. Its sequence and return value are not reliable under standard C overflow semantics.
execl()
Synopsis
int execl( const char *path, const char *arg, ...)
Function
Executes a file located in given path with specified arguments.
Inputs
path - Pathname of the file to execute. arg - First argument passed to the executed file. ... - Other arguments passed to the executed file.
Result
Returns -1 and sets errno appropriately in case of error, otherwise doesn't return.
execlp()
Synopsis
int execlp( const char *file, const char *arg, ...)
Function
Executes a file with given name. The search paths for the executed file are paths specified in the PATH environment variable.
Inputs
file - Name of the file to execute. arg - First argument passed to the executed file. ... - Other arguments passed to the executed file.
Result
Returns -1 and sets errno appropriately in case of error, otherwise doesn't return.
execv()
Synopsis
int execv( const char *path, char *const argv[])
Function
Executes a file located in given path with specified arguments.
Inputs
path - Pathname of the file to execute. argv - Array of arguments given to main() function of the executed file.
Result
Returns -1 and sets errno appropriately in case of error, otherwise doesn't return.
execve()
Synopsis
int execve( const char *filename, char *const argv[], char *const envp[])
Function
Executes a file with given name.
Inputs
filename - Name of the file to execute. argv - Array of arguments provided to main() function of the executed file. envp - Array of environment variables passed as environment to the executed program.
Result
Returns -1 and sets errno appropriately in case of error, otherwise doesn't return.
execvp()
Synopsis
int execvp( const char *file, char *const argv[])
Function
Executes a file with given name. The search paths for the executed file are paths specified in the PATH environment variable.
Inputs
file - Name of the file to execute. argv - Array of arguments given to main() function of the executed file.
Result
Returns -1 and sets errno appropriately in case of error, otherwise doesn't return.
fchdir()
Synopsis
int fchdir( int fd )
Function
Change the current working directory to the directory given as an open file descriptor.
Inputs
fd - File descriptor of the directory to change to.
Result
If the current directory was changed successfully, zero is returned. Otherwise, -1 is returned and errno set appropriately.
Notes
At program exit, the current working directory will be changed back to the one that was current when the program first started. If you do not desire this behavior, use dos.library/CurrentDir() instead.
fchmod()
Synopsis
int fchmod( int filedes, mode_t mode)
Function
Change permission bits of a file specified by an open file descriptor.
Inputs
filedes - File descriptor of the file mode - Permission bits to set
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
Notes
See chmod() documentation for more details about the mode parameter.
See also
fchmodat()
Synopsis
int fchmodat( int dirfd, const char *restrict pathname, mode_t mode, int flags)
Function
Like chmod(), but a relative pathname is resolved against the directory referenced by dirfd instead of the current directory.
Inputs
dirfd - descriptor of an open directory, or AT_FDCWD pathname - file to change mode - new permission bits flags - 0 or AT_SYMLINK_NOFOLLOW (ignored: AROS has no lchmod())
Result
0 on success, -1 with errno set on failure.
fchown()
Synopsis
int fchown( int fd, uid_t owner, gid_t group)
Notes
Not implemented.
fclose()
Synopsis
int fclose( FILE * stream)
Function
Closes a stream.
Inputs
stream - Stream to close.
Result
Upon successful completion 0 is returned. Otherwise, EOF is returned and the global variable errno is set to indicate the error. In either case no further access to the stream is possible.
fcntl()
Synopsis
int fcntl( int fd, int cmd, ...)
Function
Perform operation specified in cmd on the file descriptor fd.
Some operations require additional arguments, in this case they
follow the cmd argument. The following operations are available:
F_DUPFD (int) - Duplicate file descriptor fd as the lowest numbered
file descriptor greater or equal to the operation
argument.
F_GETFD (void) - Read the file descriptor flags
F_SETFD (int) - Set the file descriptor flags to value given in
the operation argument
F_GETFL (void) - Read the file status flags
F_SETFL (int) - Set the file status flags to value given in the
operation argument.
File descriptor flags are zero or more ORed constants:
FD_CLOEXEC - File descriptor will be closed during execve()
File descriptor flags are not copied during duplication of file
descriptors.
File status flags are the flags given as mode parameter to open()
function call. You can change only a few file status flags in opened
file descriptor: O_NONBLOCK, O_APPEND and O_ASYNC. Any other file
status flags passed in F_SETFL argument will be ignored.
All duplicated file descriptors share the same set of file status
flags.
Inputs
fd - File descriptor to perform operation on. cmd - Operation specifier. ... - Operation arguments.
Result
The return value of the function depends on the performed operation:
F_DUPFD - New duplicated file descriptor
F_GETFD - File descriptor flags
F_SETFD - 0
F_GETFL - File status flags
F_SETFL - 0 on success, -1 on error. In case of error a global errno
variable is set.
See also
fdopen()
Synopsis
FILE *fdopen( int filedes, const char *mode )
Function
function associates a stream with an existing file descriptor.
Inputs
filedes - The descriptor the stream has to be associated with
mode - The mode of the stream (same as with fopen()) must be compatible
with the mode of the file descriptor. The file
position indicator of the new stream is set to that
belonging to filedes, and the error and end-of-file indicators
are cleared. Modes "w" or "w+" do not cause truncation of the
file. The file descriptor is not duplicated, and
will be closed when the stream created by fdopen is
closed.
Result
NULL on error or the new stream associated with the descriptor. The new descriptor returned by the call is the lowest numbered descriptor currently not in use by the process.
See also
fdopendir()
Synopsis
DIR *fdopendir( int fd)
Function
Creates a directory stream for the directory referenced by the open file descriptor fd (from open() with O_DIRECTORY, openat(), or dirfd()). The descriptor is then owned by the stream and is closed by closedir().
Inputs
fd - descriptor of an open directory
Result
A directory stream, or NULL with errno set (EBADF if fd is not open, ENOTDIR if it does not refer to a directory).
See also
feof()
Synopsis
int feof( FILE * stream)
Function
Test the EOF-Flag of a stream. This flag is set automatically by any function which recognizes EOF. To clear it, call clearerr().
Inputs
stream - The stream to be tested.
Result
!= 0, if the stream is at the end of the file, 0 otherwise.
Notes
This function must not be used in a shared library or in a threaded application.
See also
ferror()
Synopsis
int ferror( FILE * stream)
Function
Test the error flag of a stream. This flag is set automatically by any function that detects an error. To clear it, call clearerr().
Inputs
stream - The stream to be tested.
Result
!= 0, if the stream had an error, 0 otherwise.
See also
fflush()
Synopsis
int fflush( FILE * stream)
Function
Flush a stream. If the stream is an input stream, then the stream is synchronized for unbuffered I/O. If the stream is an output stream, then any buffered data is written.
Inputs
stream - Flush this stream. May be NULL. In this case, all
output streams are flushed.
Result
0 on success or EOF on error.
fgetc()
Synopsis
int fgetc( FILE * stream
Function
Read one character from the stream. If there is no character available or an error occurred, the function returns EOF.
Inputs
stream - Read from this stream
Result
The character read or EOF on end of file or error.
See also
fgetpos()
Synopsis
int fgetpos( FILE * stream, fpos_t * pos)
Function
Get the current position in a stream. This function is equivalent to ftell(). However, on some systems fpos_t may be a complex structure, so this routine may be the only way to portably get the position of a stream.
Inputs
stream - The stream to get the position from. pos - Pointer to the fpos_t position structure to fill.
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
See also
fgetpos64()
Synopsis
int fgetpos64( FILE * stream, __fpos64_t * pos)
Function
Get the current position in a stream. This function is equivalent to ftell(). However, on some systems fpos_t may be a complex structure, so this routine may be the only way to portably get the position of a stream.
Inputs
stream - The stream to get the position from. pos - Pointer to the fpos_t position structure to fill.
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
See also
fgets()
Synopsis
char * fgets( char * buffer, int size, FILE * stream)
Function
Read one line of characters from the stream into the buffer.
Reading will stop, when a newline ('\n') is encountered, EOF
or when the buffer is full. If a newline is read, then it is
put into the buffer. The last character in the buffer is always
'\0' (Therefore at most size-1 characters can be read in one go).
Inputs
buffer - Write characters into this buffer size - This is the size of the buffer in characters. stream - Read from this stream
Result
buffer or NULL in case of an error or EOF.
Example
// Read a file line by line
char line[256];
// Read until EOF
while (fgets (line, sizeof (line), fh))
{
// Evaluate the line
}
fileno()
Synopsis
int fileno( FILE *stream)
Function
Returns the descriptor associated with the stream
Inputs
strem - the stream to get the descriptor from
Result
The integer descriptor
See also
flock()
Synopsis
int flock( int fd, int operation)
Function
Apply or remove an advisory lock on open file descriptor fd. Operation
argument can be one of the following constants:
LOCK_SH - Place a shared lock on the file specified by fd. More that
one process can hold a shared lock on a given file at a
time.
LOCK_EX - Place an exclusive lock on the file specified by fd. Only
one process can hold an exclusive lock on a given file at
a time.
LOCK_UN - Remove an existing lock from the file specified by fd.
LOCK_EX operation blocks if there is a lock already placed on the
file. LOCK_SH blocks if there is an exclusive lock already placed
on the file. If you want to do a non-blocking request, OR the
operation specifier with LOCK_NB constant. In this case flock() will
return -1 instead of blocking and set errno to EWOULDBLOCK.
Advisory locks created with flock() are shared among duplicated file
descriptors.
Inputs
fd - File descriptor of the file you want to place or remove lock from. operation - Lock operation to be performed.
Result
0 on success, -1 on error. In case of error a global errno variable is set.
Notes
Locks placed with flock() are only advisory, they place no restrictions to any file or file descriptor operations.
Bugs
It's currently possible to remove lock placed by another process.
flockfile()
Synopsis
void flockfile( FILE *file)
Function
Obtain exclusive access to the file.
fnmatch()
Synopsis
int fnmatch( const char * pattern, const char * string, int flags )
Function
Matches 'string' against the shell wildcard pattern 'pattern'.
Inputs
pattern - The pattern, which may contain '*', '?' and [...].
string - The string to match against the pattern.
flags - A combination of FNM_NOESCAPE, FNM_PATHNAME, FNM_PERIOD,
FNM_LEADING_DIR and FNM_CASEFOLD.
Result
0 if the string matches, FNM_NOMATCH if it does not.
fopen()
Synopsis
FILE * fopen( const char * pathname, const char * mode)
Function
Opens a file with the specified name in the specified mode.
Inputs
pathname - Path and filename of the file you want to open.
mode - How to open the file:
r: Open for reading. The stream is positioned at the
beginning of the file.
r+: Open for reading and writing. The stream is positioned
at the beginning of the file.
w: Open for writing. If the file doesn't exist, then
it is created. If it does already exist, then
it is truncated. The stream is positioned at the
beginning of the file.
w+: Open for reading and writing. If the file doesn't
exist, then it is created. If it does already
exist, then it is truncated. The stream is
positioned at the beginning of the file.
a: Open for writing. If the file doesn't exist, then
it is created. The stream is positioned at the
end of the file.
a+: Open for reading and writing. If the file doesn't
exist, then it is created. The stream is positioned
at the end of the file.
b: Open in binary more. This has no effect and is ignored.
Result
A pointer to a FILE handle or NULL in case of an error. When NULL is returned, then errno is set to indicate the error.
Notes
On 32bit systems, fopen and related operations only work with 32bit filesystems/files. Anything larger than 2 GB needs to use the correct 64bit structures and functions. This function must not be used in a shared library or in a threaded application.
Bugs
Most modes are not supported right now.
fopen64()
Synopsis
FILE * fopen64( const char * pathname, const char * mode)
Function
Opens a file with the specified name in the specified mode.
Inputs
pathname - Path and filename of the file you want to open.
mode - How to open the file:
r: Open for reading. The stream is positioned at the
beginning of the file.
r+: Open for reading and writing. The stream is positioned
at the beginning of the file.
w: Open for writing. If the file doesn't exist, then
it is created. If it does already exist, then
it is truncated. The stream is positioned at the
beginning of the file.
w+: Open for reading and writing. If the file doesn't
exist, then it is created. If it does already
exist, then it is truncated. The stream is
positioned at the beginning of the file.
a: Open for writing. If the file doesn't exist, then
it is created. The stream is positioned at the
end of the file.
a+: Open for reading and writing. If the file doesn't
exist, then it is created. The stream is positioned
at the end of the file.
b: Open in binary more. This has no effect and is ignored.
Result
A pointer to a FILE handle or NULL in case of an error. When NULL is returned, then errno is set to indicate the error.
Notes
Provides access larger to files that may be larger than 2 GB, if the underlying filesystem supports it. This function must not be used in a shared library or in a threaded application.
Bugs
Most modes are not supported right now.
See also
fprintf()
Synopsis
int fprintf( FILE * fh, const char * format, ...)
Function
Format a string with the specified arguments and write it to the stream.
Inputs
fh - Write to this stream format - How to format the arguments ... - The additional arguments
Result
The number of characters written to the stream or EOF on error.
fputc()
Synopsis
int fputc( int c, FILE * stream)
Function
Write one character to the specified stream.
Inputs
c - The character to output stream - The character is written to this stream
Result
The character written or EOF on error.
fputs()
Synopsis
int fputs( const char * str, FILE * stream)
Function
Write a string to the specified stream.
Inputs
str - Output this string... fh - ...to this stream
Result
> 0 on success and EOF on error.
fread()
Synopsis
size_t fread( void * buf, size_t size, size_t nblocks, FILE * stream)
Function
Read an amount of bytes from a stream.
Inputs
buf - The buffer to read the bytes into size - Size of one block to read nblocks - The number of blocks to read stream - Read from this stream
Result
The number of blocks read. This may range from 0 when the stream contains no more blocks up to nblocks. In case of an error, 0 is returned.
freelocale()
Synopsis
void freelocale( locale_t loc)
Function
Accept a locale object for release. No storage is freed by this implementation.
Inputs
loc - Locale object returned by newlocale(). The argument
is not inspected or dereferenced.
Result
None. The function does not change errno.
Notes
Include <locale.h>. newlocale() returns shared static objects with no caller-owned allocation. This call neither invalidates the object nor changes the active locale. Do not release these objects with free().
See also
freopen()
Synopsis
FILE *freopen( const char *path, const char *mode, FILE *stream )
Function
Opens the file whose name is the string pointed to by path and associates the stream pointed to by stream with it.
Inputs
path - the file to open
mode - The mode of the stream (same as with fopen()) must be compatible
with the mode of the file descriptor. The file
position indicator of the new stream is set to that
belonging to fildes, and the error and end-of-file indicators
are cleared. Modes "w" or "w+" do not cause truncation of the
file. The file descriptor is not duplicated, and
will be closed when the stream created by fdopen is
closed.
stream - the stream to which the file will be associated.
Result
NULL on error or stream.
fscanf()
Synopsis
int fscanf( FILE * fh, const char * format, ...)
Function
Scan a string with the specified arguments and write the results in the specified parameters.
Inputs
fh - Read from this stream format - How to convert the input into the arguments ... - Write the result in these arguments
Result
The number of converted arguments.
See also
fseek()
Synopsis
int fseek( FILE * stream, long offset, int whence)
Function
Change the current position in a stream.
Inputs
stream - Modify this stream
offset, whence - How to modify the current position. whence
can be SEEK_SET, then offset is the absolute position
in the file (0 is the first byte), SEEK_CUR then the
position will change by offset (ie. -5 means to move
5 bytes to the beginning of the file) or SEEK_END.
SEEK_END means that the offset is relative to the
end of the file (-1 is the last byte and 0 is
the EOF).
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
Bugs
Not fully compatible with ISO fseek, especially in 'ab' and 'a+b' modes Since it's not possible to use Seek() for directories, this implementation fails with EISDIR for directory file descriptors.
fseeko()
Synopsis
int fseeko( FILE * stream, off_t offset, int whence)
Function
Change the current position in a stream.
Inputs
stream - Modify this stream
offset, whence - How to modify the current position. whence
can be SEEK_SET, then offset is the absolute position
in the file (0 is the first byte), SEEK_CUR then the
position will change by offset (ie. -5 means to move
5 bytes to the beginning of the file) or SEEK_END.
SEEK_END means that the offset is relative to the
end of the file (-1 is the last byte and 0 is
the EOF).
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
Notes
on 32bit platforms, off_t is a 32bit value, and so the 64bit version (fseeko64) is needed to work with large files. off_t is 64bit natively on 64bit platforms.
Bugs
Not fully compatible with ISO fseeko, especially in 'ab' and 'a+b' modes
See also
fseeko64()
Synopsis
int fseeko64( FILE * stream, off64_t offset, int whence)
Function
Change the current position in a stream.
Inputs
stream - Modify this stream
offset, whence - How to modify the current position. whence
can be SEEK_SET, then offset is the absolute position
in the file (0 is the first byte), SEEK_CUR then the
position will change by offset (ie. -5 means to move
5 bytes to the beginning of the file) or SEEK_END.
SEEK_END means that the offset is relative to the
end of the file (-1 is the last byte and 0 is
the EOF).
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
Notes
Allows seeking on files that may be larger than 2GB, if the underlying filesystem supports it.
Bugs
Not fully compatible with ISO fseeko, especially in 'ab' and 'a+b' modes
See also
fsetpos()
Synopsis
int fsetpos( FILE * stream, const fpos_t * pos)
Function
Change the current position in a stream. This function is equivalent to fseek() with whence set to SEEK_SET. However, on some systems fpos_t may be a complex structure, so this routine may be the only way to portably reposition a stream.
Inputs
stream - Modify this stream pos - The new position in the stream.
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
See also
fsetpos64()
Synopsis
int fsetpos64( FILE * stream, const __fpos64_t * pos)
Function
Change the current position in a stream. This function is equivalent to fseek() with whence set to SEEK_SET. However, on some systems fpos_t may be a complex structure, so this routine may be the only way to portably reposition a stream.
Inputs
stream - Modify this stream pos - The new position in the stream.
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
See also
fstat()
Synopsis
int fstat( int fd, struct stat *sb)
Function
Returns information about a file specified by an open file descriptor. Information is stored in stat structure. Consult stat() documentation for detailed description of that structure.
Inputs
filedes - File descriptor of the file sb - Pointer to stat structure that will be filled by the fstat() call.
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
See also
fstat64()
Synopsis
int fstat64( int fd, struct stat64 *sb)
Function
Returns information about a file specified by an open file descriptor. Information is stored in stat64 structure. Consult stat() documentation for detailed description of that structure.
Inputs
filedes - File descriptor of the file sb - Pointer to stat structure that will be filled by fstat64() call.
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
See also
fstatat()
Synopsis
int fstatat( int dirfd, const char *restrict pathname, struct stat *restrict statbuf, int flags)
Function
Like stat() (or lstat() when AT_SYMLINK_NOFOLLOW is given), but a relative pathname is resolved against the directory referenced by dirfd instead of the current directory.
Inputs
dirfd - descriptor of an open directory, or AT_FDCWD pathname - file to examine statbuf - receives the result flags - 0 or AT_SYMLINK_NOFOLLOW
Result
0 on success, -1 with errno set on failure.
fstatvfs()
Synopsis
int fstatvfs( int fd, struct statvfs *buf)
Function
Check a file descriptor for a filesystem-statistics query. Retrieving the statistics is not implemented.
Inputs
fd - Open posixc file descriptor. buf - Pointer to caller-owned struct statvfs storage.
Result
-1 with errno set to EINVAL if buf is NULL, or EBADF if fd is not recognized as a posixc file descriptor. The NULL-buffer check takes precedence. Otherwise returns 0 without writing any part of *buf.
Notes
Include <sys/statvfs.h>. The descriptor remains open. After validation, the function emits a not-implemented diagnostic through kprintf().
Bugs
A zero return does not indicate that filesystem statistics were obtained. Do not read an uninitialized buffer after this call. Use statvfs() with a suitable pathname instead.
See also
fsync()
Synopsis
int fsync( int fd)
ftell()
Synopsis
long ftell( FILE * stream)
Function
Tell the current position in a stream.
Inputs
stream - Obtain position of this stream
Result
The position on success and -1 on error. If an error occurred, the global variable errno is set.
ftello()
Synopsis
off_t ftello( FILE *stream)
Function
Returns the current position in a stream.
Inputs
stream - Query this stream
Notes
on 32bit platforms, off_t is a 32bit value, and so the 64bit version (ftello64) is needed to work with large files. off_t is 64bit natively on 64bit platforms.
ftello64()
Synopsis
off64_t ftello64( FILE *stream)
Function
Returns the current position in a stream.
Inputs
stream - Query this stream
Notes
Returns the position in files that may be larger than 2 GB, if the underlying filesystem supports it.
See also
ftime()
Synopsis
int ftime( struct timeb *tb)
Function
Get info on current time and timezone.
Inputs
tb - Structure to fill in time, it has the following fields
* time: time in seconds since UNIX epoch
* millitm: milliseconds since last second
* timezone: minutes time west of Greenwich
* dstflag: type of daylight saving time
millitm is currently always multiple of 1000
dstflag is the same as from timezone information from the
gettimeofday() function.
Result
Always returns 0.
Notes
This function is deprecated and not present anymore in POSIX.1-2008. This function should not be used in new code and old code should be fixed to remove usage. As an alternative gettimeofday() can be used.
See also
ftruncate()
Synopsis
int ftruncate( int fd, off_t length)
Function
Truncate a file to a specified length
Inputs
fd - the descriptor of the file being truncated.
The file must be open for writing
lenght - The file will have at most this size
Result
0 on success or -1 on errorr.
Notes
If the file previously was larger than this size, the extra data is lost. If the file previously was shorter, it is unspecified whether the file is left unchanged or is extended. In the latter case the extended part reads as zero bytes.
See also
ftruncate64()
Synopsis
int ftruncate64( int fd, __off64_t length)
Function
Truncate a file to a specified length
Inputs
fd - the descriptor of the file being truncated.
The file must be open for writing
lenght - The file will have at most this size
Result
0 on success or -1 on errorr.
Notes
If the file previously was larger than this size, the extra data is lost. If the file previously was shorter, it is unspecified whether the file is left unchanged or is extended. In the latter case the extended part reads as zero bytes.
See also
funlockfile()
Synopsis
void funlockfile( FILE *file)
Function
Relinquish exclusive access to the file.
fwrite()
Synopsis
size_t fwrite( const void * restrict buf, size_t size, size_t nblocks, FILE * restrict stream)
Function
Write an amount of bytes to a stream.
Inputs
buf - The buffer to write to the stream size - Size of one block to write nblocks - The number of blocks to write stream - Write to this stream
Result
The number of blocks written. If no error occurred, this is nblocks. Otherwise examine errno for the reason of the error.
See also
gcvt()
Synopsis
char * gcvt( double number, int ndigit, char * buf )
Function
Converts a number to a minimal length NULL terminated ASCII string. It produces ndigit significant digits in either printf F format or E format.
Inputs
number - The number to convert. ndigits - The number of significant digits that the string has to have. buf - The buffer that will contain the result string.
Result
The address of the string pointed to by buf.
Notes
This function is deprecated and not present anymore in POSIX.1-2008. This function should not be used in new code and old code should be fixed to remove usage. This function is part of libposixc.a and may be removed in the future.
See also
getc()
Synopsis
int getc( FILE * stream)
Function
Read one character from the stream. If there is no character available or an error occurred, the function returns EOF.
Inputs
stream - Read from this stream
Result
The character read or EOF on end of file or error.
See also
getc_unlocked()
Synopsis
int getc_unlocked( FILE * stream)
Inputs
stream - Read from this stream
Result
The character read or EOF on end of file or error.
See also
getchar()
Synopsis
int getchar(
Function
Read one character from the standard input stream. If there is no character available or an error occurred, the function returns EOF.
Result
The character read or EOF on end of file or error.
getcwd()
Synopsis
char *getcwd( char *buf, size_t size)
Function
Get the current working directory.
Inputs
buf - Pointer of the buffer where the path is to be stored size - The size of the above buffer
Result
Copies the absolute pathname of the current working directory to the buffer. If the pathname is longer than the buffer (with lenght "size") NULL is returned and errno set to ERANGE. Otherwise the pointer to the buffer is returned.
Notes
If buf is NULL this function will allocate the buffer itself using malloc() and the specified size "size". If size is 0, too, the buffer is allocated to hold the whole path. It is possible and recommended to free() this buffer yourself! The path returned does not have to be literally the same as the one given to chdir. See NOTES from chdir for more explanation.
See also
getdelim()
Synopsis
ssize_t getdelim( char ** restrict lineptr, size_t * restrict n, int delim, FILE * restrict stream)
Function
Read characters from stream up to and including the first occurrence of the delimiter byte delim (or end-of-file), storing them in a dynamically (re)allocated buffer.
Inputs
lineptr - address of a pointer to the buffer. If *lineptr is NULL (or
*n is 0) a buffer is allocated; otherwise it is grown with
realloc() as needed. The caller must free() it.
n - address of the buffer's size; updated when it is (re)grown.
delim - the delimiter byte at which reading stops.
stream - the stream to read from.
Result
The number of characters read, including the delimiter but not the terminating NUL, or -1 on error or end-of-file with nothing read (errno is set on error).
Notes
The result is always NUL-terminated.
getegid()
Synopsis
gid_t getegid( void)
Function
Returns the effective group ID of the calling process
See also
getentropy()
Synopsis
int getentropy( void *buffer, size_t length)
Function
Fill a buffer with high-quality random bytes suitable for seeding a pseudo-random generator or for cryptographic keys. The bytes are obtained from entropy.resource. The call does not block and always draws from the best source the running system provides (software collection plus, where available, CPU hardware entropy).
Inputs
buffer - where to store the random bytes. length - the number of bytes wanted; must not exceed 256.
Result
0 on success. On failure -1 is returned and errno is set: EINVAL - length is greater than 256. EFAULT - buffer is NULL. EIO - no entropy source is available, or it failed to deliver.
Example
unsigned char seed[32];
if (getentropy(seed, sizeof(seed)) == 0)
; // seed[] now holds 32 random bytes
Notes
Unlike rand()/random(), getentropy() is not seeded by the caller and has no reproducible sequence. It is the POSIX counterpart of the BSD arc4random_buf() (see <stdlib.h>).
See also
getenv()
Synopsis
char *getenv( const char *name)
Function
Get an environment variable.
Inputs
name - Name of the environment variable.
Result
Pointer to the variable's value, or NULL on failure.
Notes
The returned contents of the environment variable is cached per PosixCBase and per variable name. So the returned value is valid and does not change until a next call to getenv with the same PosixCBase and the same name.
getfsstat()
Synopsis
int getfsstat( struct statfs *buf, long bufsize, int flags)
Function
Gets information about mounted filesystems.
Inputs
buf - pointer to statfs structures where information about filesystems
will be stored or NULL
bufsize - size of buf in bytes
flags - not used
Result
If buf is NULL number of mounted filesystems is returned. If buf is not null, information about mounted filesystems is stored in statfs structures up to bufsize bytes
Bugs
f_flags, f_files, f_ffree and f_fsid.val are always set to 0 f_mntfromname is set to an empty string
getgid()
Synopsis
gid_t getgid( void)
Function
Returns the real group ID of the calling process
See also
getgrent()
Synopsis
struct group *getgrent( void)
Function
Operates on the group database via netinfo.device interface, Providing a convenient unix-compatible interface to the group unit of the netinfo.device.
See also
getgrgid()
Synopsis
struct group *getgrgid( gid_t gid)
Function
Operates on the group database via netinfo.device interface, Providing a convenient unix-compatible interface to the group unit of the netinfo.device.
See also
getgrgid_r()
Synopsis
int getgrgid_r( gid_t gid, struct group *grp, char *buffer, size_t bufsize, struct group **result)
Function
Reentrant version of getgrgid(). Looks up a group database entry by group ID and stores the result in caller-provided storage.
Inputs
gid - the group ID to look up.
grp - caller-provided struct group to fill in.
buffer - caller-provided storage for the strings and member list
pointed to by grp.
bufsize - the size of buffer in bytes.
result - on success set to grp, or to NULL when no entry was found.
Result
0 on success (including "not found", with *result set to NULL). On error a positive error number is returned (ERANGE if buffer was too small, or e.g. ENOSYS if the group database is unavailable).
Notes
Unlike getgrgid(), the returned data is stored in caller-provided memory and is not overwritten by a subsequent lookup.
See also
getgrnam()
Synopsis
struct group *getgrnam( const char *name)
Function
Operates on the group database via netinfo.device interface, Providing a convenient unix-compatible interface to the group unit of the netinfo.device.
See also
getgrnam_r()
Synopsis
int getgrnam_r( const char *name, struct group *grp, char *buffer, size_t bufsize, struct group **result)
Function
Reentrant version of getgrnam(). Looks up a group database entry by name and stores the result in caller-provided storage.
Inputs
name - the group name to look up.
grp - caller-provided struct group to fill in.
buffer - caller-provided storage for the strings and member list
pointed to by grp.
bufsize - the size of buffer in bytes.
result - on success set to grp, or to NULL when no entry was found.
Result
0 on success (including "not found", with *result set to NULL). On error a positive error number is returned (ERANGE if buffer was too small, or e.g. ENOSYS if the group database is unavailable).
Notes
Unlike getgrnam(), the returned data is stored in caller-provided memory and is not overwritten by a subsequent lookup.
See also
getgroups()
Synopsis
int getgroups( int gidsetlen, gid_t *gidset)
Notes
Not implemented.
getline()
Synopsis
ssize_t getline( char ** restrict lineptr, size_t * restrict n, FILE * restrict stream)
Function
Read a line from stream, up to and including the next newline (or end-of-file), into a dynamically (re)allocated buffer. Equivalent to getdelim() with a delimiter of '\n'.
Inputs
lineptr - address of a pointer to the buffer (allocated/grown as
needed; the caller must free() it).
n - address of the buffer's size.
stream - the stream to read from.
Result
The number of characters read, including the newline but not the terminating NUL, or -1 on error or end-of-file with nothing read.
Notes
The result is always NUL-terminated.
See also
getloadavg()
Synopsis
int getloadavg( double loadavg[], int n)
Notes
Not implemented.
getlogin()
Synopsis
char * getlogin( )
Notes
Not implemented.
getopt()
Synopsis
int getopt( int nargc, char * const nargv[], const char *ostr)
Notes
Due to the usage of global variables this function is now put in the static link library. This means each compilation unit using getopt has its own getopt state tracking.
See also
getopt_long()
Synopsis
int getopt_long( int nargc, char * const *nargv, const char *options, const struct option *long_options, int *idx)
Function
The getopt_long() function is similar to getopt() but it accepts options
in two forms: words and characters. The getopt_long() function provides
a superset of the functionality of getopt(3). The getopt_long() function
can be used in two ways. In the first way, every long option understood
by the program has a corresponding short option, and the option structure
is only used to translate from long options to short options. When used
in this fashion, getopt_long() behaves identically to getopt(3). This is
a good way to add long option processing to an existing program with the
minimum of rewriting.
In the second mechanism, a long option sets a flag in the option struc-
ture passed, or will store a pointer to the command line argument in the
option structure passed to it for options that take arguments. Addition-
ally, the long option's argument may be specified as a single argument
with an equal sign, e.g.,
myprogram --myoption=somevalue
When a long option is processed, the call to getopt_long() will return 0.
For this reason, long option processing without shortcuts is not back-
wards compatible with getopt(3).
It is possible to combine these methods, providing for long options pro-
cessing with short option equivalents for some options. Less frequently
used options would be processed as long options only.
The getopt_long() call requires a structure to be initialized describing
the long options. The structure is:
struct option {
char *name;
int has_arg;
int *flag;
int val;
};
The name field should contain the option name without the leading double
dash.
The has_arg field should be one of:
no_argument no argument to the option is expect
required_argument an argument to the option is required
optional_argument an argument to the option may be presented.
If flag is not NULL, then the integer pointed to by it will be set to the
value in the val field. If the flag field is NULL, then the val field
will be returned. Setting flag to NULL and setting val to the corre-
sponding short option will make this function act just like getopt(3).
If the longindex field is not NULL, then the integer pointed to by it
will be set to the index of the long option relative to longopts.
The last element of the longopts array has to be filled with zeroes.
Inputs
See above
Result
If the flag field in struct option is NULL, getopt_long() and getopt_long_only() return the value specified in the val field, which is usually just the corresponding short option. If flag is not NULL, these functions return 0 and store val in the location pointed to by flag. These functions return `:' if there was a missing option argument, `?' if the user specified an unknown or ambiguous option, and -1 when the argu- ment list has been exhausted.
Notes
Due to the usage of global variables this function is now put in the static link library. This means each compilation unit using getopt_long has its own getopt_long state tracking.
See also
getopt_long_only()
Synopsis
int getopt_long_only( int nargc, char * const *nargv, const char *options, const struct option *long_options, int *idx)
Function
The getopt_long_only() function behaves identically to getopt_long() with the exception that long options may start with `-' in addition to `--'. If an option starting with `-' does not match a long option but does match a single-character option, the single-character option is returned.
See also
getpass()
Synopsis
char * getpass( const char *prompt)
Function
(obsolete) prompt for a password.
Notes
This function returns a pointer to a static buffer
containing (the first PASS_MAX bytes of) the password without the
trailing newline, terminated by a null byte ('\0').
Function is not re-entrant. Results will be overwritten by
subsequent calls.
getpgid()
Synopsis
pid_t getpgid( pid_t pid)
Function
Returns the process group ID for the specified process with ID 'pid'.
getpgrp()
Synopsis
pid_t getpgrp( void)
Notes
Not implemented.
getpid()
Synopsis
pid_t getpid( )
Function
Returns the process ID of the calling process
Result
The process ID of the calling process.
getppid()
Synopsis
pid_t getppid( void)
Function
Returns the Parent process ID of the calling processes.
getpwent()
Synopsis
struct passwd *getpwent( void)
Function
Operates on the user database via netinfo.device interface, Providing a convenient unix-compatible interface to the password unit of the netinfo.device.
See also
getpwnam()
Synopsis
struct passwd *getpwnam( const char *name)
Function
Operates on the user database via netinfo.device interface, Providing a convenient unix-compatible interface to the password unit of the netinfo.device.
See also
getpwnam_r()
Synopsis
int getpwnam_r( const char *name, struct passwd *pwd, char *buffer, size_t bufsize, struct passwd **result)
Function
Reentrant version of getpwnam(). Looks up a user database entry by name and stores the result in caller-provided storage.
Inputs
name - the username to look up. pwd - caller-provided struct passwd to fill in. buffer - caller-provided storage for the strings pointed to by pwd. bufsize - the size of buffer in bytes. result - on success set to pwd, or to NULL when no entry was found.
Result
0 on success (including "not found", with *result set to NULL). On error a positive error number is returned (ERANGE if buffer was too small, or e.g. ENOSYS if the user database is unavailable).
Notes
Unlike getpwnam(), the returned data is stored in caller-provided memory and is not overwritten by a subsequent lookup.
See also
getpwuid()
Synopsis
struct passwd *getpwuid( uid_t uid)
Function
Operates on the user database via netinfo.device interface, Providing a convenient unix-compatible interface to the password unit of the netinfo.device.
See also
getpwuid_r()
Synopsis
int getpwuid_r( uid_t uid, struct passwd *pwd, char *buffer, size_t bufsize, struct passwd **result)
Function
Reentrant version of getpwuid(). Looks up a user database entry by user ID and stores the result in caller-provided storage.
Inputs
uid - the user ID to look up. pwd - caller-provided struct passwd to fill in. buffer - caller-provided storage for the strings pointed to by pwd. bufsize - the size of buffer in bytes. result - on success set to pwd, or to NULL when no entry was found.
Result
0 on success (including "not found", with *result set to NULL). On error a positive error number is returned (ERANGE if buffer was too small, or e.g. ENOSYS if the user database is unavailable).
Notes
Unlike getpwuid(), the returned data is stored in caller-provided memory and is not overwritten by a subsequent lookup.
See also
getrlimit()
Synopsis
int getrlimit( int resource, struct rlimit *rlp)
Function
Get the limits of certain system resources
Inputs
resource - the resource type to get rlp - returned resource information
Result
On success, returns 0. -1 and errno on error.
See also
getrusage()
Synopsis
int getrusage( int who, struct rusage *usage)
Function
Get resource usage information for the calling process.
Inputs
who - RUSAGE_SELF (RUSAGE_CHILDREN is refused: AROS keeps no
child accounting)
usage - filled with the accounting data
Result
0 on success, -1 with errno on error.
Notes
ru_utime is the calling task's CPU time, read from task.resource (TaskTag_CPUTime). AROS has no user/system time split, so ru_stime is 0. The fourteen BSD extension fields (ru_maxrss through ru_nivcsw) are zero: AROS tracks none of them. Zeroing documented untracked extensions is exactly what Linux does for fields it does not maintain; the POSIX fields are real. The timeval task.resource returns is normalised here: its rounding ((tv_nsec + 500) / 1000) can yield tv_usec == 1000000, which is not a valid timeval.
Bugs
RUSAGE_SELF covers the calling task only. POSIX requires it to cover all threads of the process, but posixc threads are separate exec tasks (see pthread_create()) with no per-process enumeration facility posixc could walk, so other threads' CPU time is not included. Whether task.resource should grow a process-wide query is an open question. RUSAGE_CHILDREN (and any other who value) fails with EINVAL: AROS has no waited-for children's CPU time source (wait()/waitpid() collect none). If child accounting ever lands, revisit.
See also
gets()
Synopsis
char * gets( char * buffer)
Function
Read one line of characters from the standard input stream into
the buffer. Reading will stop, when a newline ('\n') is encountered,
EOF or when the buffer is full. If a newline is read, then it is
replaced by '\0'. The last character in the buffer is always '\0'.
Inputs
buffer - Write characters into this buffer
Result
buffer or NULL in case of an error or EOF.
Bugs
Never use this function. gets() does not know how large the buffer is and will continue to store characters past the end of the buffer if it has not encountered a newline or EOF yet. Use fgets() instead.
See also
gettimeofday()
Synopsis
int gettimeofday( struct timeval * tv, struct timezone * tz)
Function
Return the current time and/or timezone.
Inputs
tv - If this pointer is non-NULL, the current time will be
stored here. The structure looks like this:
struct timeval
{
long tv_sec; // seconds
long tv_usec; // microseconds
};
tz - If this pointer is non-NULL, the current timezone will be
stored here. The structure looks like this:
struct timezone
{
int tz_minuteswest; // minutes west of Greenwich
int tz_dsttime; // type of dst correction
};
With daylight savings times defined as follows :
DST_NONE // not on dst
DST_USA // USA style dst
DST_AUST // Australian style dst
DST_WET // Western European dst
DST_MET // Middle European dst
DST_EET // Eastern European dst
DST_CAN // Canada
DST_GB // Great Britain and Eire
DST_RUM // Romania
DST_TUR // Turkey
DST_AUSTALT // Australian style with shift in 1986
And the following macros are defined to operate on this :
timerisset(tv) - TRUE if tv contains a time
timercmp(tv1, tv2, cmp) - Return the result of the
comparison "tv1 cmp tv2"
timerclear(tv) - Clear the timeval struct
Result
The number of seconds.
Example
struct timeval tv;
// Get the current time and print it
gettimeofday (&tv, NULL);
printf ("Seconds = %ld, uSec = %ld\n", tv->tv_sec, tv->tv_usec);
Notes
This function must not be used in a shared library or in a threaded application.
getuid()
Synopsis
uid_t getuid( void)
Function
Returns the real user ID of the calling process.
See also
getw()
Synopsis
int getw( FILE *stream)
Notes
Implemented as static inline function. This is not a POSIX function, please use standard fread() function.
See also
gmtime_r()
Synopsis
struct tm * gmtime_r( const time_t * tt, struct tm * tm)
Function
The gmtime_r() function converts the calendar time tt (assumed to be UTC) to a broken-down time representation, expressed in Coordinated Universal Time (UTC). It is the reentrant variant of gmtime(): the result is stored in the caller-supplied tm rather than in a shared static buffer.
Inputs
tt - The time to convert tm - A struct tm to store the result in
Result
The pointer passed in tm, containing the broken-down time in Coordinated Universal Time (UTC).
Example
time_t tt; struct tm tm; // Get the time time (&tt); // and convert it gmtime_r (&tt, &tm);
ioctl()
Synopsis
int ioctl( int fd, int request, ...)
Function
Control device. Function to manipulate and fetch special device parameters.
Inputs
fd - file descriptor
request - ioctl request id, containing request type, input or output
type and argument size in bytes. Use macros and defines
from <sys/ioctl.h>:
TIOCGWINSZ - fill in rows, columns, width and height of
console window
... - Other arguments for the specified request
Result
DOS handles return -1 with errno set to EBADF (invalid descriptor) or ENOTTY (unsupported operation). Foreign hooks define their own return values and errors.
Example
#include <stdio.h>
#include <unistd.h>
#include <sys/ioctl.h>
{
int ret;
struct winsize w;
ret = ioctl(STDOUT_FILENO, TIOCGWINSZ, &w);
if(ret)
{
printf("ERROR: %d\n", ret);
}
else
{
printf ("columns: %4d\n", w.ws_col);
printf ("lines: %4d\n", w.ws_row);
printf ("width: %4d\n", w.ws_xpixel);
printf ("height: %4d\n", w.ws_ypixel);
}
}
Notes
DOS terminal geometry is currently unsupported. ACTION_DISK_INFO does not provide a validated geometry contract: mainline CON stores a use count in id_InUse, not a console.device IO request pointer. See rom/filesys/console_handler/con_handler.c, ACTION_DISK_INFO: id->id_InUse = fh->usecount; Foreign descriptor hooks retain their own request handling.
Bugs
TIOCGWINSZ on DOS handles returns ENOTTY until a terminal-control protocol is available. The output structure is left unchanged.
isatty()
Synopsis
int isatty( int fd)
iswalnum_l()
Synopsis
int iswalnum_l( wint_t wc, locale_t locale)
Function
Test whether the current C locale classifies wc as a letter or decimal digit.
Inputs
wc - Wide character value to classify, or WEOF.
locale - Locale handle. Ignored by this implementation;
it is neither dereferenced nor retained.
Result
1 if wc belongs to the requested class; otherwise 0. WEOF and values outside the classification table return 0. No error is reported through errno.
Notes
Include <wctype.h> with _POSIX_C_SOURCE set to at least 200809L. Classification is limited to U+0000 through U+00FF when __WCHAR_MAX__ exceeds 255, and to U+0000 through U+007F otherwise. Selecting C.UTF-8 does not extend this range.
Bugs
The supplied locale does not select the classification table. The result follows the current C locale instead. The built-in fallback table omits some Latin-1 letters.
See also
iswalpha_l()
Synopsis
int iswalpha_l( wint_t wc, locale_t locale)
Function
Test whether the current C locale classifies wc as a letter.
Inputs
wc - Wide character value to classify, or WEOF.
locale - Locale handle. Ignored by this implementation;
it is neither dereferenced nor retained.
Result
1 if wc belongs to the requested class; otherwise 0. WEOF and values outside the classification table return 0. No error is reported through errno.
Notes
Include <wctype.h> with _POSIX_C_SOURCE set to at least 200809L. Classification is limited to U+0000 through U+00FF when __WCHAR_MAX__ exceeds 255, and to U+0000 through U+007F otherwise. Selecting C.UTF-8 does not extend this range.
Bugs
The supplied locale does not select the classification table. The result follows the current C locale instead. The built-in fallback table also classifies ASCII digits as letters and omits some Latin-1 letters.
See also
iswblank_l()
Synopsis
int iswblank_l( wint_t wc, locale_t locale)
Function
Test whether the current C locale classifies wc as a horizontal blank.
Inputs
wc - Wide character value to classify, or WEOF.
locale - Locale handle. Ignored by this implementation;
it is neither dereferenced nor retained.
Result
1 if wc belongs to the requested class; otherwise 0. WEOF and values outside the classification table return 0. No error is reported through errno.
Notes
Include <wctype.h> with _POSIX_C_SOURCE set to at least 200809L. Classification is limited to U+0000 through U+00FF when __WCHAR_MAX__ exceeds 255, and to U+0000 through U+007F otherwise. Selecting C.UTF-8 does not extend this range.
Bugs
The supplied locale does not select the classification table. The result follows the current C locale instead.
See also
iswcntrl_l()
Synopsis
int iswcntrl_l( wint_t wc, locale_t locale)
Function
Test whether the current C locale classifies wc as a control character.
Inputs
wc - Wide character value to classify, or WEOF.
locale - Locale handle. Ignored by this implementation;
it is neither dereferenced nor retained.
Result
1 if wc belongs to the requested class; otherwise 0. WEOF and values outside the classification table return 0. No error is reported through errno.
Notes
Include <wctype.h> with _POSIX_C_SOURCE set to at least 200809L. Classification is limited to U+0000 through U+00FF when __WCHAR_MAX__ exceeds 255, and to U+0000 through U+007F otherwise. Selecting C.UTF-8 does not extend this range.
Bugs
The supplied locale does not select the classification table. The result follows the current C locale instead. The built-in fallback table does not classify U+0009 through U+000D or U+0080 through U+009F as controls.
See also
iswdigit_l()
Synopsis
int iswdigit_l( wint_t wc, locale_t locale)
Function
Test whether the current C locale classifies wc as a decimal digit.
Inputs
wc - Wide character value to classify, or WEOF.
locale - Locale handle. Ignored by this implementation;
it is neither dereferenced nor retained.
Result
1 if wc belongs to the requested class; otherwise 0. WEOF and values outside the classification table return 0. No error is reported through errno.
Notes
Include <wctype.h> with _POSIX_C_SOURCE set to at least 200809L. Classification is limited to U+0000 through U+00FF when __WCHAR_MAX__ exceeds 255, and to U+0000 through U+007F otherwise. Selecting C.UTF-8 does not extend this range.
Bugs
The supplied locale does not select the classification table. The result follows the current C locale instead.
See also
iswgraph_l()
Synopsis
int iswgraph_l( wint_t wc, locale_t locale)
Function
Test whether the current C locale classifies wc as a graphic character.
Inputs
wc - Wide character value to classify, or WEOF.
locale - Locale handle. Ignored by this implementation;
it is neither dereferenced nor retained.
Result
1 if wc belongs to the requested class; otherwise 0. WEOF and values outside the classification table return 0. No error is reported through errno.
Notes
Include <wctype.h> with _POSIX_C_SOURCE set to at least 200809L. Classification is limited to U+0000 through U+00FF when __WCHAR_MAX__ exceeds 255, and to U+0000 through U+007F otherwise. Selecting C.UTF-8 does not extend this range.
Bugs
The supplied locale does not select the classification table. The result follows the current C locale instead. The built-in fallback table omits many graphic Latin-1 characters.
See also
iswlower_l()
Synopsis
int iswlower_l( wint_t wc, locale_t locale)
Function
Test whether the current C locale classifies wc as a lowercase letter.
Inputs
wc - Wide character value to classify, or WEOF.
locale - Locale handle. Ignored by this implementation;
it is neither dereferenced nor retained.
Result
1 if wc belongs to the requested class; otherwise 0. WEOF and values outside the classification table return 0. No error is reported through errno.
Notes
Include <wctype.h> with _POSIX_C_SOURCE set to at least 200809L. Classification is limited to U+0000 through U+00FF when __WCHAR_MAX__ exceeds 255, and to U+0000 through U+007F otherwise. Selecting C.UTF-8 does not extend this range.
Bugs
The supplied locale does not select the classification table. The result follows the current C locale instead. The built-in fallback table omits U+00B5 and U+00FF.
See also
iswprint_l()
Synopsis
int iswprint_l( wint_t wc, locale_t locale)
Function
Test whether the current C locale classifies wc as a printable character.
Inputs
wc - Wide character value to classify, or WEOF.
locale - Locale handle. Ignored by this implementation;
it is neither dereferenced nor retained.
Result
1 if wc belongs to the requested class; otherwise 0. WEOF and values outside the classification table return 0. No error is reported through errno.
Notes
Include <wctype.h> with _POSIX_C_SOURCE set to at least 200809L. Classification is limited to U+0000 through U+00FF when __WCHAR_MAX__ exceeds 255, and to U+0000 through U+007F otherwise. Selecting C.UTF-8 does not extend this range.
Bugs
The supplied locale does not select the classification table. The result follows the current C locale instead. The built-in fallback table omits many printable Latin-1 characters.
See also
iswpunct_l()
Synopsis
int iswpunct_l( wint_t wc, locale_t locale)
Function
Test whether the current C locale classifies wc as a punctuation character.
Inputs
wc - Wide character value to classify, or WEOF.
locale - Locale handle. Ignored by this implementation;
it is neither dereferenced nor retained.
Result
1 if wc belongs to the requested class; otherwise 0. WEOF and values outside the classification table return 0. No error is reported through errno.
Notes
Include <wctype.h> with _POSIX_C_SOURCE set to at least 200809L. Classification is limited to U+0000 through U+00FF when __WCHAR_MAX__ exceeds 255, and to U+0000 through U+007F otherwise. Selecting C.UTF-8 does not extend this range.
Bugs
The supplied locale does not select the classification table. The result follows the current C locale instead. The generated table recognizes Unicode punctuation categories, excluding symbols such as plus and dollar signs. The built-in fallback table instead recognizes ASCII punctuation and symbols, but no Latin-1 punctuation.
See also
iswspace_l()
Synopsis
int iswspace_l( wint_t wc, locale_t locale)
Function
Test whether the current C locale classifies wc as a whitespace character.
Inputs
wc - Wide character value to classify, or WEOF.
locale - Locale handle. Ignored by this implementation;
it is neither dereferenced nor retained.
Result
1 if wc belongs to the requested class; otherwise 0. WEOF and values outside the classification table return 0. No error is reported through errno.
Notes
Include <wctype.h> with _POSIX_C_SOURCE set to at least 200809L. Classification is limited to U+0000 through U+00FF when __WCHAR_MAX__ exceeds 255, and to U+0000 through U+007F otherwise. Selecting C.UTF-8 does not extend this range.
Bugs
The supplied locale does not select the classification table. The result follows the current C locale instead.
See also
iswupper_l()
Synopsis
int iswupper_l( wint_t wc, locale_t locale)
Function
Test whether the current C locale classifies wc as an uppercase letter.
Inputs
wc - Wide character value to classify, or WEOF.
locale - Locale handle. Ignored by this implementation;
it is neither dereferenced nor retained.
Result
1 if wc belongs to the requested class; otherwise 0. WEOF and values outside the classification table return 0. No error is reported through errno.
Notes
Include <wctype.h> with _POSIX_C_SOURCE set to at least 200809L. Classification is limited to U+0000 through U+00FF when __WCHAR_MAX__ exceeds 255, and to U+0000 through U+007F otherwise. Selecting C.UTF-8 does not extend this range.
Bugs
The supplied locale does not select the classification table. The result follows the current C locale instead.
See also
iswxdigit_l()
Synopsis
int iswxdigit_l( wint_t wc, locale_t locale)
Function
Test whether the current C locale classifies wc as a hexadecimal digit.
Inputs
wc - Wide character value to classify, or WEOF.
locale - Locale handle. Ignored by this implementation;
it is neither dereferenced nor retained.
Result
1 if wc belongs to the requested class; otherwise 0. WEOF and values outside the classification table return 0. No error is reported through errno.
Notes
Include <wctype.h> with _POSIX_C_SOURCE set to at least 200809L. Classification is limited to U+0000 through U+00FF when __WCHAR_MAX__ exceeds 255, and to U+0000 through U+007F otherwise. Selecting C.UTF-8 does not extend this range.
Bugs
The supplied locale does not select the classification table. The result follows the current C locale instead.
See also
jrand48()
Synopsis
long jrand48( unsigned short xseed[3])
kill()
Synopsis
int kill( pid_t pid, int sig)
Notes
Not implemented.
lcong48()
Synopsis
void lcong48( unsigned short p[7])
link()
Synopsis
int link( const char *oldpath, const char *newpath)
Notes
Not implemented.
localeconv_l()
Synopsis
struct lconv * localeconv_l( locale_t loc)
Function
Return the default numeric-formatting data when loc is NULL. Locale-object queries are not implemented correctly.
Inputs
loc - Pass NULL. Non-NULL locale handles, including those
returned by newlocale(), are unsupported by this
implementation. Do not pass LC_GLOBAL_LOCALE.
Result
For NULL, the borrowed static structure returned by localeconv(): a decimal point of ".", empty separator, grouping and monetary strings, and CHAR_MAX for numeric monetary fields. Do not modify or free the structure or its strings. No storage is allocated for the result.
Notes
Include <locale.h>. Every call emits a not-implemented diagnostic through kprintf(), including the NULL case. The function does not select or retain a locale.
Bugs
For non-NULL loc, the function assumes that the object starts with an embedded struct lconv. The actual locale objects use a different layout. The returned pointer is not a valid formatting-data result for those handles; reading through it can access unrelated or invalid data. This failure is not reported with a NULL result or errno.
See also
localtime_r()
Synopsis
struct tm * localtime_r( const time_t * tt, struct tm * tm)
Function
The localtime_r() function converts the calendar time tt (assumed to be UTC) to a broken-down time representation, expressed in the user's local timezone. It is the reentrant variant of localtime(): the result is stored in the caller-supplied tm rather than in a shared static buffer. See localtime() for a description of the members of the tm structure.
Inputs
tt - A time in seconds from the 1. Jan 1970 tm - A struct tm to store the result in
Result
The pointer passed in tm.
Example
time_t tt; struct tm tm; // Get time time (&tt); // Break time up localtime_r (&tt, &tm);
lrand48()
Synopsis
long lrand48( void)
lseek()
Synopsis
off_t lseek( int filedes, off_t offset, int whence)
Function
Reposition read/write file offset
Inputs
filedef - the filedescriptor being modified
offset, whence -
How to modify the current position. whence
can be SEEK_SET, then offset is the absolute position
in the file (0 is the first byte), SEEK_CUR then the
position will change by offset (ie. -5 means to move
5 bytes to the beginning of the file) or SEEK_END.
SEEK_END means that the offset is relative to the
end of the file (-1 is the last byte and 0 is
the EOF).
Result
The new position on success and -1 on error. If an error occurred, the global variable errno is set.
Bugs
File is extended with zeros if desired position is beyond the end of file. Since it's not possible to use Seek() for directories, this implementation fails with EISDIR for directory file descriptors.
See also
lseek64()
Synopsis
__off64_t lseek64( int filedes, __off64_t offset, int whence)
Function
Reposition read/write file offset
Inputs
filedef - the filedescriptor being modified
offset, whence -
How to modify the current position. whence
can be SEEK_SET, then offset is the absolute position
in the file (0 is the first byte), SEEK_CUR then the
position will change by offset (ie. -5 means to move
5 bytes to the beginning of the file) or SEEK_END.
SEEK_END means that the offset is relative to the
end of the file (-1 is the last byte and 0 is
the EOF).
Result
The new position on success and -1 on error. If an error occurred, the global variable errno is set.
Bugs
File is extended with zeros if desired position is beyond the end of file. Since it's not possible to use Seek() for directories, this implementation fails with EISDIR for directory file descriptors.
See also
lstat()
Synopsis
int lstat( const char *path, struct stat *sb)
Function
Returns information about a file like stat does except that lstat does not follow symbolic links. Information is stored in stat structure. Consult stat() documentation for detailed description of that structure.
Inputs
path - Pathname of the file sb - Pointer to stat structure that will be filled by the lstat() call.
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
See also
lstat64()
Synopsis
int lstat64( const char *path, struct stat64 *sb)
Function
Returns information about a file like stat does except that lstat does not follow symbolic links. Information is stored in stat structure. Consult stat() documentation for detailed description of that structure.
Inputs
path - Pathname of the file sb - Pointer to stat structure that will be filled by the lstat() call.
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
mbsnrtowcs()
Synopsis
size_t mbsnrtowcs( wchar_t * restrict dst, const char ** restrict src, size_t nms, size_t len, mbstate_t * restrict ps ) FUNCTION Converts at most 'nms' bytes from the multibyte string pointed to by *src into wide characters, storing at most 'len' wide characters in dst. The conversion uses the current locale (UTF-8 assumed here) and updates the src pointer to point past the last converted multibyte character.
Inputs
dst - Pointer to destination wide character buffer (may be NULL).
src - Address of the multibyte character string pointer. The pointer is updated
during conversion. If dst is NULL, the function returns the number
of wide characters that would result from the conversion.
nms - Maximum number of bytes to convert from the multibyte string.
len - Maximum number of wide characters to write.
ps - Conversion state object (ignored in this implementation).
Result
Returns the number of wide characters written or needed. Returns (size_t)-1 on conversion error and sets errno to EILSEQ.
Notes
This implementation assumes stateless UTF-8 encoding and does not currently use mbstate_t. It wraps around mbrtowc().
mkdir()
Synopsis
int mkdir( const char *path, mode_t mode)
Function
Make a directory file
Inputs
path - the path of the directory being created mode - the permission flags for the directory
Result
0 on success or -1 on errorr.
See also
mknod()
Synopsis
int mknod( const char *pathname, mode_t mode, dev_t dev)
Notes
Not implemented.
mkstemp()
Synopsis
int mkstemp( char *template)
Inputs
A template that must end with 'XXXXXX'
Result
A file descriptor of opened temporary file or -1 on error.
mktemp()
Synopsis
char *mktemp( char *template)
Function
Make a unique temporary file name.
Inputs
template - template to change into unique filename
Result
Returns template.
Notes
Template must end in "XXXXXX" (i.e at least 6 X's). Prior to this paragraph being created, mktemp() sometimes produced filenames with '/' in them. AROS doesn't like that at all. Fortunately, the bug in this function which produced it has been fixed. -- blippy For clarity, define the HEAD of the template to be the part before the tail, and the TAIL to be the succession of X's. So in, T:temp.XXXXXX , the head is T:temp. and the tail is XXXXXX .
Bugs
Cannot create more than 26 filenames for the same process id. This is because the "bumping" is only done to the first tail character - it should be generalized to bump more characters if necessary.
mrand48()
Synopsis
long mrand48( void)
nanosleep()
Synopsis
int nanosleep( const struct timespec * req, struct timespec *rem)
Function
Suspends program execution for a given number of nanoseconds.
Inputs
req - time to wait rem - remaining time, if nanosleep was interrupted by a signal
Result
0 on success, -1 on error
Notes
Currently at most a resolution of milliseconds is supported.
newlocale()
Synopsis
locale_t newlocale( int category_mask, const char *locale_name, locale_t base)
Function
Create a locale object for locale_name (POSIX.1-2008). AROS's libc knows the "C" (= "POSIX", = "") locale and, with wide wchar_t, "C.UTF-8"; those are returned as shared, immutable objects.
Inputs
category_mask - LC_*_MASK bits to take from locale_name; every
category comes from the same table here, so the
mask only has to be valid.
locale_name - "C", "POSIX", "" (the default), "C.UTF-8".
base - modified and returned unchanged when non-NULL and
not LC_GLOBAL_LOCALE (the objects are shared, so
"modifying" the C locale into the C locale is the
identity).
Result
The locale object, or NULL with errno set: EINVAL for a bad mask or LC_GLOBAL_LOCALE base, ENOENT for an unknown locale name.
Notes
Returning NULL for "C" (the previous stub) broke every consumer that builds its C-locale handle at startup â libc++ does exactly that (newlocale(LC_ALL_MASK, "C", 0)) and then calls islower_l()/ toupper_l() with it, which dereference the NULL locale: every std::ostream << double crashed on AROS.
See also
nl_langinfo()
Synopsis
char * nl_langinfo( nl_item item)
Function
Return information for one of the implemented locale items.
Inputs
item - CODESET, ABDAY_1, DAY_1, D_FMT, RADIXCHAR, THOUSEP,
AM_STR or PM_STR. All other values return an empty
string.
Result
Borrowed string; do not modify or free it. RADIXCHAR is "." and THOUSEP is empty. ABDAY_1 and DAY_1 select Sunday. Formatting failure also returns an empty string, so an empty result does not distinguish failure from valid data or an unsupported item. See BUGS before relying on results.
Notes
Include <langinfo.h>. Copy the result before another call that uses the same buffer: weekday queries share one buffer, and AM_STR and PM_STR share another. D_FMT uses a separate buffer. Calls are not reentrant; synchronize shared use. Weekday and AM/PM text comes from strftime(), which uses the default system locale when available and English fallback strings otherwise. It does not use the C-library locale handle. D_FMT reads the current local date.
Bugs
CODESET calls setlocale(LC_CTYPE, NULL), which resets the C-library locale to "C" in this implementation; the result is then "unknown". D_FMT returns a date formatted as month/day/two-digit-year, not a format string. Time-read failure is not checked before the date is formatted. The strftime() dependency can write beyond the buffer when a weekday name occupies 100 or more bytes, or AM/PM text occupies 10 or more bytes. It also leaves opened system locale references unreleased. No reliable error indicator is provided for these defects.
nl_langinfo_l()
Synopsis
char * nl_langinfo_l( nl_item item, locale_t loc)
Function
Call nl_langinfo() while attempting a temporary C-library locale change.
Inputs
item - Item accepted by nl_langinfo().
loc - Readable locale object, normally from newlocale(),
or NULL to skip the requested switch. LC_GLOBAL_LOCALE
is not supported and must not be passed.
Result
The borrowed result of nl_langinfo(), or an empty string if saving the locale name fails. Do not modify or free it. The buffer-sharing rules and result defects of nl_langinfo() apply. Empty results do not identify a unique error.
Notes
Include <langinfo.h>. The function allocates a temporary copy of a locale name and frees it before returning. It does not retain loc. Calls to Forbid() and Permit() bracket the operation; they do not make the returned buffers private. Use ordinary task context and synchronize shared use.
Bugs
The initial setlocale(LC_ALL, NULL) resets the C-library locale to "C" instead of querying it. The saved name is therefore "C", and the previous locale is lost, including on allocation failure. A normal return restores "C". Locale-change failures are ignored. Weekday and AM/PM queries use the default system locale, not loc; CODESET resets the C-library locale again. This function does not provide independent locale-object queries. The formatting and resource defects listed for nl_langinfo() also apply.
See also
nrand48()
Synopsis
long nrand48( unsigned short xseed[3])
open()
Synopsis
int open( const char * pathname, int flags, ...)
Function
Opens a file with the specified flags and name.
Inputs
pathname - Path and filename of the file you want to open.
flags - Most be exactly one of: O_RDONLY, O_WRONLY or O_RDWR
to open a file for reading, writing or for reading and
writing.
The mode can be modified by or'ing the following bits in:
O_CREAT: Create the file if it doesn't exist (only for
O_WRONLY or O_RDWR). If this flag is set, then
open() will look for a third parameter mode. mode
must contain the access modes for the file
(mostly 0644).
O_EXCL: Only with O_CREAT. If the file does already exist,
then open() fails. See BUGS.
O_NOCTTY:
O_TRUNC: If the file exists, then it gets overwritten. This
is the default and the opposite to O_APPEND.
O_APPEND: If the file exists, then the starting position for
writes is the end of the file.
O_NONBLOCK or O_NDELAY: Opens the file in non-blocking mode.
If there is no data in the file, then read() on a
terminal will return immediately instead of waiting
until data arrives. Has no effect on write().
O_SYNC: The process will be stopped for each write() and the
data will be flushed before the write() returns.
This ensures that the data is physically written
when write() returns. If this flag is not specified,
the data is written into a buffer and flushed only
once in a while.
Result
-1 for error or a file descriptor for use with read(), write(), etc.
Notes
If the filesystem doesn't allow to specify different access modes for users, groups and others, then the user modes are used. This function must not be used in a shared library or in a threaded application.
Bugs
The flag O_EXCL is not very reliable if the file resides on a NFS filesystem. Most flags are not supported right now.
See also
openat()
Synopsis
int openat( int dirfd, const char *restrict pathname, int flags, ...)
Function
Like open(), but a relative pathname is resolved against the directory referenced by the descriptor dirfd instead of the current directory. dirfd may be AT_FDCWD to use the current directory.
Inputs
dirfd - descriptor of an open directory (see opendir(), dirfd(),
or open() with O_DIRECTORY), or AT_FDCWD
pathname - file to open; absolute names ("Volume:...", "/...") ignore dirfd
flags - as for open(); O_DIRECTORY requires the target to be a
directory, O_CLOEXEC sets FD_CLOEXEC on the new descriptor
mode - permissions used when O_CREAT creates the file
Result
The new file descriptor, or -1 with errno set.
Notes
The directory is made current with dos.library/CurrentDir() only for the duration of the call.
See also
opendir()
Synopsis
DIR *opendir( const char *name)
Function
Opens a directory
Inputs
pathname - Path and filename of the directory you want to open.
Result
NULL for error or a directory stream
pathconf()
Synopsis
long pathconf( const char *path, int name)
Function
Return a fixed pathname limit selected by name. The filesystem containing path is not queried.
Inputs
path - Ignored. The pointer is not dereferenced, and the
pathname is neither resolved nor validated.
name - _PC_PATH_MAX is the supported public query. See
BUGS for the incorrectly implemented name-limit query.
Result
PATH_MAX (1024) for _PC_PATH_MAX. The implementation also returns FILENAME_MAX (256) for _POSIX_NAME_MAX (32). All other values return -1. errno is unchanged in every case.
Notes
Include <unistd.h>. The result does not depend on whether path exists or on the filesystem that would resolve it.
Bugs
The name-limit branch tests _POSIX_NAME_MAX, a minimum limit constant, instead of the query selector _PC_NAME_MAX. _PC_NAME_MAX is not defined by the current public header. _PC_VDISABLE is declared but returns -1. A -1 result does not distinguish an unsupported selector from an indeterminate limit. The fixed positive results are not verified limits for the supplied pathname.
perror()
Synopsis
void perror( const char *string )
Function
looks up the language-dependent error message string affiliated with an error number and writes it, followed by a newline, to the standard error stream.
Inputs
string - the string to prepend the error message. If NULL only the error
message will be printed, otherwise the error message will be
separated from string by a colon.
pipe()
Synopsis
int pipe( int *pipedes)
popen()
Synopsis
FILE * popen( const char * command, const char * mode)
Function
"opens" a process by creating a pipe, spawning a new process and invoking the shell.
Inputs
command - Pointer to a null terminated string containing the command
to be executed by the shell.
mode - Since a pipe is unidirectional, mode can be only one of
r: Open for reading. After popen() returns, the stream can
be used to read from it, as if it were a normal file stream,
in order to get the command's output.
w: Open for writing. After popen() returns, the stream can
be used to write to it, as if it were a normal file stream,
in order to provide the command with some input.
Result
A pointer to a FILE handle or NULL in case of an error. When NULL is returned, then errno is set to indicate the error.
Notes
This function must not be used in a shared library or in a threaded application.
posix_fadvise()
Synopsis
int posix_fadvise( int fd, off_t offset, off_t len, int advice)
Function
Announce the access pattern the application intends to use on the region of the file starting at offset and spanning len bytes (or to the end of the file if len is 0), so that the system may optimise its caching accordingly.
Inputs
fd - An open file descriptor.
offset - Start of the region the advice applies to.
len - Length of the region, 0 meaning "to end of file".
advice - One of POSIX_FADV_NORMAL, POSIX_FADV_SEQUENTIAL,
POSIX_FADV_RANDOM, POSIX_FADV_NOREUSE, POSIX_FADV_WILLNEED
or POSIX_FADV_DONTNEED.
Result
0 on success, otherwise an error number (errno is not set):
EBADF - fd is not a valid file descriptor.
EINVAL - advice is not a recognised value, offset or len is
negative, or fd refers to a directory.
Notes
AROS filesystems provide no interface for caching hints, so the advice is validated and then ignored. This matches the behaviour permitted by POSIX: the call is purely advisory and has no effect on the semantics of subsequent operations on the file.
posix_memalign()
Synopsis
int posix_memalign( void **memptr, size_t alignment, size_t size)
Function
Allocate aligned memory.
Inputs
memptr - Pointer to a place to store the pointer to allocated memory.
alignment - Alignment of allocated memory. The address of the
allocated memory will be a multiple of this value, which
must be a power of two and a multiple of sizeof(void *).
size - How much memory to allocate.
Result
Returns zero on success. Returns EINVAL if the alignment parameter was not a power of two, or was not a multiple of sizeof(void *). Returns ENOMEM if there was insufficient memory to fulfill the request.
Notes
Memory allocated by posix_memalign() should be freed with free(). If not, it will be freed when the program terminates. If an error occurs, errno will not be set.
pread()
Synopsis
ssize_t pread( int d, void *buf, size_t nbytes, off_t offset)
Function
Read up to nbytes from the file at offset, leaving the file offset of the descriptor unchanged.
Inputs
d - file descriptor to read from buf - where to put the data nbytes - number of bytes to read offset - position in the file to read from
Result
The number of bytes read, 0 at or beyond the end of the file, or -1 with errno set.
Notes
See pread64(), which this calls.
pread64()
Synopsis
ssize_t pread64( int d, void *buf, size_t nbytes, __off64_t offset)
Function
Read up to nbytes from the file at offset, leaving the file offset of the descriptor unchanged.
Inputs
d - file descriptor to read from buf - where to put the data nbytes - number of bytes to read offset - position in the file to read from
Result
The number of bytes read, 0 at or beyond the end of the file, or -1 with errno set.
Notes
Implemented with lseek64() and read(), so unlike POSIX it is not atomic: another thread using the same descriptor at the same time may see the offset move. Since lseek() past the end extends a file, an offset at or beyond the end returns 0 without seeking.
printf()
Synopsis
int printf( const char * format, ...)
Function
Formats a list of arguments and prints them to standard out.
The format string is composed of zero or more directives: ordinary
characters (not %), which are copied unchanged to the output
stream; and conversion specifications, each of which results in
fetching zero or more subsequent arguments Each conversion
specification is introduced by the character %. The arguments must
correspond properly (after type promotion) with the conversion
specifier. After the %, the following appear in sequence:
Zero or more of the following flags:
# - specifying that the value should be converted to an
``alternate form''. For a,A,c, d, i, n, p, s, and u conversions, this
option has no effect. For o conversions, the precision of the
number is increased to force the first character of the output
string to a zero (except if a zero value is printed with an
explicit precision of zero). For x and X conversions, a non-zero
result has the string `0x' (or `0X' for X conversions) prepended to
it. For e, E, f, F,g, and G conversions, the result will always
contain a decimal point, even if no digits follow it (normally, a
decimal point appears in the results of those conversions only if a
digit follows). For g and G conversions, trailing zeros are not
removed from the result as they would otherwise be.
0 - specifying zero padding. For all conversions except n, the
converted value is padded on the left with zeros rather than
blanks. For f,F conversion, or if a precision is given with a numeric
conversion (d, i, o,u, i, x, and X), the 0 flag is ignored.
- - (a negative field width flag) indicates the converted
value is to be left adjusted on the field boundary. Except for n
conversions, the converted value is padded on the right with
blanks, rather than on the left with blanks or zeros. A -
overrides a 0 if both are given.
- (a space) specifying that a blank should be left before a
positive number produced by a signed conversion (d, e, E, f, g, G,
or i). + specifying that a sign always be placed before a number
produced by a signed conversion. A + overrides a space if both are
used.
' - specifying that in a numerical argument the output is to
be grouped if the locale information indicates any. Note that many
versions of gcc cannot parse this option and will issue a warning.
An optional decimal digit string specifying a minimum field
width. If the converted value has fewer characters than the field
width, it will be padded with spaces on the left (or right, if the
left-adjustment flag has been given) to fill out the field width.
An optional precision, in the form of a period (`.') followed
by an optional digit string. If the digit string is omitted, the
precision is taken as zero. This gives the minimum number of digits
to appear for d, i, o, u, x, and X conversions, the number of
digits to appear after the decimal-point for e, E, and f
conversions, the maximum number of significant digits for g and G
conversions, or the maximum number of characters to be printed from
a string for s conversions.
The optional character h, specifying that a following d, i,
o, u, x, or X conversion corresponds to a short int or unsigned
short int argument, or that a following n conversion corresponds to
a pointer to a short int argument.
The optional character l (ell) specifying that a following d,
i, o, u, x, or X conversion applies to a pointer to a long int or
unsigned long int argument, or that a following n conversion
corresponds to a pointer to a long int argument. Linux provides a
non ANSI compliant use of two l flags as a synonym to q or L. Thus
ll can be used in combination with float conversions. This usage
is, however, strongly discouraged.
The character L specifying that a following e, E,
f, g, or G conversion corresponds to a long double
argument, or a following d, i, o, u, x, or X conversion corresponds to a long long argument. Note
that long long is not specified in ANSI C and
therefore not portable to all architectures.
The optional character q. This is equivalent to L. See the
STANDARDS and BUGS sections for comments on the use of ll, L, and
q.
A Z character specifying that the following integer (d, i, o,
u, i, x, and X), conversion corresponds to a size_t argument.
A character that specifies the type of conversion to be
applied.
A field width or precision, or both, may be indicated by an
asterisk `*' instead of a digit string. In this case, an int
argument supplies the field width or precision. A negative field
width is treated as a left adjustment flag followed by a positive
field width; a negative precision is treated as though it were
missing.
The conversion specifiers and their meanings are:
diouxX - The int (or appropriate variant) argument is
converted to signed decimal (d and i), unsigned octal (o, unsigned
decimal (u, or unsigned hexadecimal (x and X) notation. The letters
abcdef are used for x conversions; the letters ABCDEF are used for
X conversions. The precision, if any, gives the minimum number of
digits that must appear; if the converted value requires fewer
digits, it is padded on the left with zeros.
aA - (TODO) The double argument is rounded and converted to the C99
floating-point number in hexadecimal notation - preserving all
bits of precision, and presenting them in a robust way.
eE - The double argument is rounded and converted in the style
[<->]d.dddedd where there is one digit before the decimal-point
character and the number of digits after it is equal to the
precision; if the precision is missing, it is taken as 6; if the
precision is zero, no decimal-point character appears. An E
conversion uses the letter E (rather than e) to introduce the
exponent. The exponent always contains at least two digits; if the
value is zero, the exponent is 00.
fF - The double argument is rounded and converted to decimal
notation in the style [-]ddd.ddd, where the number of digits after
the decimal-point character is equal to the precision
specification. If the precision is missing, it is taken as 6; if
the precision is explicitly zero, no decimal-point character
appears. If a decimal point appears, at least one digit appears
before it.
g - The double argument is converted in style f or e (or E for
G conversions). The precision specifies the number of significant
digits. If the precision is missing, 6 digits are given; if the
precision is zero, it is treated as 1. Style e is used if the
exponent from its conversion is less than -4 or greater than or
equal to the precision. Trailing zeros are removed from the
fractional part of the result; a decimal point appears only if it
is followed by at least one digit.
c - The int argument is converted to an unsigned char, and the
resulting character is written.
s - The ``char *'' argument is expected to be a pointer to an
array of character type (pointer to a string). Characters from the
array are written up to (but not including) a terminating NUL
character; if a precision is specified, no more than the number
specified are written. If a precision is given, no null character
need be present; if the precision is not specified, or is greater
than the size of the array, the array must contain a terminating
NUL character.
p - The ``void *'' pointer argument is printed in hexadecimal
(as if by %#x or %#lx).
n - The number of characters written so far is stored into the
integer indicated by the ``int *'' (or variant) pointer argument.
No argument is converted.
% - A `%' is written. No argument is converted. The complete
conversion specification is `%%'.
In no case does a non-existent or small field width cause
truncation of a field; if the result of a conversion is wider than
the field width, the field is expanded to contain the conversion
result.
Inputs
format - Format string as described above ... - Arguments for the format string
Result
The number of characters written to stdout or EOF on error.
Example
To print a date and time in the form `Sunday, July 3,
10:02', where weekday and month are pointers to strings:
#include <stdio.h>
fprintf (stdout, "%s, %s %d, %.2d:%.2d\n",
weekday, month, day, hour, min);
To print to five decimal places:
#include <math.h>
#include <stdio.h>
fprintf (stdout, "pi = %.5f\n", 4 * atan(1.0));
To allocate a 128 byte string and print into it:
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
char *newfmt(const char *fmt, ...)
{
char *p;
va_list ap;
if ((p = malloc(128)) == NULL)
return (NULL);
va_start(ap, fmt);
(void) vsnprintf(p, 128, fmt, ap);
va_end(ap);
return (p);
}
Bugs
All functions are fully ANSI C3.159-1989 conformant, but provide the additional flags q, Z and ' as well as an additional behaviour of the L and l flags. The latter may be considered to be a bug, as it changes the behaviour of flags defined in ANSI C3.159-1989. The effect of padding the %p format with zeros (either by the 0 flag or by specifying a precision), and the benign effect (i.e., none) of the # flag on %n and %p conversions, as well as nonsensical combinations such as are not standard; such combinations should be avoided. Some combinations of flags defined by ANSI C are not making sense in ANSI C (e.g. %Ld). While they may have a well-defined behaviour on Linux, this need not to be so on other architectures. Therefore it usually is better to use flags that are not defined by ANSI C at all, i.e. use q instead of L in combination with diouxX conversions or ll. The usage of q is not the same as on BSD 4.4, as it may be used in float conversions equivalently to L. Because sprintf and vsprintf assume an infinitely long string, callers must be careful not to overflow the actual space; this is often impossible to assure.
pselect()
Synopsis
int pselect(
int nfds,
fd_set *restrict readfds,
fd_set *restrict writefds,
fd_set *restrict exceptfds,
const struct timespec *restrict timeout,
const sigset_t *restrict sigmask)
putc()
Synopsis
int putc( int c, FILE * stream)
Function
Write one character to the specified stream.
Inputs
c - The character to output stream - The character is written to this stream
Result
The character written or EOF on error.
See also
putchar()
Synopsis
int putchar( int c)
putenv()
Synopsis
int putenv( const char *string)
Function
Change or add an environment variable.
Inputs
string - Is of the form "name=value", where name is the variable's
name and value is its value. In case the string is of the form
"name" then the variable is removed from the environment.
Result
The putenv() function returns zero on success, or -1 if an error occurs. In such a case the errno variable is set appropriately.
Notes
This function must not be used in a shared library. Conforming to BSD4.4 in that it makes a copy of the argument string.
puts()
Synopsis
int puts( const char * str)
Function
Print a string to stdout. A newline ('\n') is emitted after the
string.
Inputs
str - Print this string
Result
> 0 on success and EOF on error. On error, the reason is put in errno.
Example
#include <errno.h>
if (puts ("Hello World.") != EOF)
fprintf (stderr, "Success");
else
fprintf (stderr, "Failure: errno=%d", errno);
putw()
Synopsis
int putw( int word, FILE *stream)
Notes
Implemented as static inline function. This is not a POSIX function, please use standard fwrite() function.
See also
rand_r()
Synopsis
int rand_r( unsigned int *seed)
Function
Returns a pseudo-random integer in the range 0 to RAND_MAX, using a caller-supplied seed pointer for reentrant behavior. The algorithm is a linear congruential generator (LCG) and matches the behavior of traditional ANSI C rand() but avoids using global state. This allows rand_r() to be safely used in multithreaded environments.
Inputs
seed - Pointer to an unsigned int used as the state of the
random number generator. The pointed-to value will be
updated on each call.
Result
Returns a pseudo-random integer value between 0 and RAND_MAX (typically 32767). The value is deterministically derived from the current seed.
Example
unsigned int seed = 12345; int r = rand_r(&seed); // safe to use in multithreaded code
Notes
- rand_r() is a POSIX extension and not part of ISO C. - It is reentrant and thread-safe, unlike rand(). - Sequences produced by rand_r() are deterministic and repeatable for a given initial seed value.
Bugs
The quality of the random sequence is limited by the LCG algorithm. It is not suitable for cryptographic use.
read()
Synopsis
ssize_t read( int fd, void * buf, size_t count)
Function
Read an amount of bytes from a file descriptor.
Inputs
fd - The file descriptor to read from buf - The buffer to read the bytes into count - Read this many bytes.
Result
The number of characters read (may range from 0 when the file descriptor contains no more characters to count) or -1 on error.
readdir()
Synopsis
struct dirent *readdir( DIR *dir)
Function
Reads a directory
Inputs
dir - the directory stream pointing to the directory being read
Result
The readdir() function returns a pointer to a dirent structure, or NULL if an error occurs or end-of-file is reached. The data returned by readdir() is overwritten by subsequent calls to readdir() for the same directory stream. According to POSIX, the dirent structure contains a field char d_name[] of unspecified size, with at most NAME_MAX characters preceding the terminating null character. Use of other fields will harm the portability of your programs.
See also
readdir64()
Synopsis
struct dirent64 *readdir64( DIR *dir)
Function
Reads a directory
Inputs
dir - the directory stream pointing to the directory being read
Result
The readdir() function returns a pointer to a dirent structure, or NULL if an error occurs or end-of-file is reached. The data returned by readdir() is overwritten by subsequent calls to readdir() for the same directory stream. According to POSIX, the dirent structure contains a field char d_name[] of unspecified size, with at most NAME_MAX characters preceding the terminating null character. Use of other fields will harm the portability of your programs.
See also
realpath()
Synopsis
char *realpath( const char *path, char *resolved_path)
Function
Resolves the absolute, canonical pathname of the given path by resolving all symbolic links, relative components, and references to `.` and `..`.
Inputs
path
Pointer to the null-terminated pathname to resolve.
resolved_path
Buffer where the resolved absolute pathname is stored.
If NULL, the function allocates a buffer of size PATH_MAX internally,
which should be freed by the caller.
Result
Returns a pointer to the resolved_path buffer on success. Returns NULL on failure, setting errno to indicate the error.
Example
char buf[PATH_MAX];
char *res = realpath("/some/path", buf);
if (res) {
// use res
} else {
// handle error
}
Notes
- The resolved path is always null-terminated. - Symbolic link loops are detected and prevented by limiting the number of symlinks followed (SYMLOOP_MAX). - The function temporarily changes the working directory internally, but restores it before returning. - The function assumes a POSIX-like environment with UTF-8 encoding. - If resolved_path is NULL, the caller is responsible for freeing the returned buffer.
Bugs
None known.
See also
remove()
Synopsis
remove( const char * pathname)
Function
Deletes a file or directory.
Inputs
pathname - Complete path to the file or directory.
Result
0 on success and -1 on error. In case of an error, errno is set.
Notes
Identical to unlink
See also
rename()
Synopsis
rename( const char * oldpath, const char * newpath )
Function
Changes the name or location of a file or directory from `oldpath` to `newpath`.
Inputs
oldpath - The current path to an existing file or directory. newpath - The new desired path for the file or directory.
Result
Returns 0 on success. Returns -1 on failure and sets errno accordingly.
Example
if (rename("/home/user/oldfile.txt", "/home/user/newfile.txt") != 0) {
perror("rename failed");
}
Notes
- The function performs path conversions for platform compatibility. - Paths with relative elements like '.' or '..' are handled. - If `newpath` resolves to "." or ".." alone, the function returns an error (EEXIST).
Bugs
None known.
rewind()
Synopsis
void rewind( FILE * stream)
Function
Sets the file position indicator for the given stream to the beginning of the file. Any error and end-of-file indicators for the stream are cleared.
Inputs
stream - Pointer to a FILE object that identifies the stream to rewind.
Result
None (void function).
Example
FILE *fp = fopen("example.txt", "r");
if (fp) {
// Read some data...
rewind(fp); // Reset to start of file
// Read again from beginning...
fclose(fp);
}
Notes
- Unlike `fseek()`, `rewind()` does not return a value. - The function clears the error and EOF indicators for the stream, allowing further I/O operations without error states.
Bugs
None known.
See also
rewinddir()
Synopsis
void rewinddir( DIR *dir)
rmdir()
Synopsis
int rmdir( const char * pathname)
Function
Deletes an empty directory.
Inputs
pathname - Complete path to the directory.
Result
0 on success and -1 on error. In case of an error, errno is set.
scandir()
Synopsis
int scandir( const char *dir, struct dirent ***namelist, int (*select)(const struct dirent *), int (*compar)(const struct dirent **, const struct dirent **) )
Function
Scan directory
Inputs
dir - Directory to be scanned
namelist - Array with the found entries.
select - Filter function which must return non-zero if entry shall be
added. If NULL all entries will be added.
compar - Function which will be used by qsort() for sorting of the
entries. The function alphasort() can be used for sorting
in alphabetical order. If NULL sorting order isn't specified.
Result
Number of entries
See also
scandir64()
Synopsis
int scandir64( const char *dir, struct dirent64 ***namelist, int (*select)(const struct dirent64 *), int (*compar)(const struct dirent64 **, const struct dirent64 **) )
Function
Scan directory
Inputs
dir - Directory to be scanned
namelist - Array with the found entries.
select - Filter function which must return non-zero if entry shall be
added. If NULL all entries will be added.
compar - Function which will be used by qsort() for sorting of the
entries. The function alphasort() can be used for sorting
in alphabetical order. If NULL sorting order isn't specified.
Result
Number of entries
See also
scanf()
Synopsis
int scanf( const char * format, ...)
Result
Returns the number of input items successfully matched and assigned. This number can be less than the number requested, or even zero, if a matching failure occurs before any assignments. If an input failure occurs before any conversions, EOF is returned.
Example
int x;
float y;
scanf("%d %f", &x, &y);
Notes
- The function reads from the standard input stream (stdin). - The behavior and supported format specifiers conform to the C standard library specification. - It is recommended to check the return value to detect input errors or mismatches.
Bugs
- Input matching is dependent on the format string correctness. - Mismatched format specifiers and argument types can lead to undefined behavior.
seed48()
Synopsis
unsigned short *seed48( unsigned short xseed[3])
seekdir()
Synopsis
void seekdir( DIR *dir, off_t offset)
select()
Synopsis
int select(
int nfds,
fd_set *restrict readfds,
fd_set *restrict writefds,
fd_set *restrict exceptfds,
struct timeval *restrict timeout)
setbuf()
Synopsis
void setbuf( FILE *stream, char *buf)
Function
Sets the buffer for the specified stream. If `buf` is not NULL, the stream is fully buffered using the provided buffer of size `BUFSIZ`. If `buf` is NULL, the stream is set to unbuffered mode (no buffering). This function is a simpler interface to `setvbuf()` and behaves according to the C standard library specification.
Inputs
stream - Pointer to a `FILE` object identifying the stream.
buf - Pointer to a buffer for stream buffering, or NULL for
unbuffered operation.
Result
This function returns no value.
Example
char buffer[BUFSIZ]; setbuf(stdout, buffer); // Use a custom buffer for stdout
Notes
- The size of the buffer used when `buf` is not NULL is fixed to `BUFSIZ`. - Use `setbuf()` before any I/O operation on the stream to ensure the buffer is set properly. - This function is equivalent to calling: `setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);`
Bugs
- Buffering behavior is implementation-dependent. - Calling `setbuf()` after I/O has started on the stream may have undefined effects.
setegid()
Synopsis
int setegid( gid_t gid)
Function
Set the effective group id of the calling process to gid.
setenv()
Synopsis
int setenv( const char *name, const char *value, int overwrite)
Function
Change or add an environment variable.
Inputs
name - Name of the environment variable,
value - Value which the variable must be set or changed to.
overwrite - If non-zero then, if a variable with the name name already
exists, its value is changed to value, otherwise is not
changed
Result
Returns zero on success, or -1 if there was insufficient space in the environment.
Notes
This function must not be used in a shared library.
seteuid()
Synopsis
int seteuid( uid_t uid)
Notes
Does not check permissions.
setgid()
Synopsis
int setgid( gid_t gid)
Function
Set the group id, and effective group id of the calling process to gid.
setgrent()
Synopsis
void setgrent( void)
Function
Operates on the group database via netinfo.device interface, Providing a convenient unix-compatible interface to the group unit of the netinfo.device.
See also
setlinebuf()
Synopsis
void setlinebuf( FILE *stream)
Notes
This is a simpler alias for setvbuf() according to manpage. This function is not part of POSIX and programmers are advised to use setvbuf() function directly. Legacy functions may be removed in the future.
See also
setpwent()
Synopsis
void setpwent( void)
Function
Operates on the user database via netinfo.device interface, Providing a convenient unix-compatible interface to the password unit of the netinfo.device.
See also
setrlimit()
Synopsis
int setrlimit( int resource, const struct rlimit *rlp)
Function
Get the limits of certain system resources
Inputs
resource - the resource type to get rlp - resource information to update
Result
On success, returns 0. -1 and errno on error.
Notes
Currently always returns -1 and errno is set to EINVAL
See also
setsid()
Synopsis
pid_t setsid( void)
Function
Returns the process group ID for the new session.
setuid()
Synopsis
int setuid( uid_t uid)
Function
Sets the user ID, and effective user ID of the calling process.
Notes
Does not check permissions.
setvbuf()
Synopsis
int setvbuf( FILE *stream, char *buf, int mode, size_t size)
Function
Sets the buffering mode and buffer size for a given stream. This function must be called after the stream is opened but before any other operations (such as reading or writing) are performed on it. The user can supply their own buffer, or pass NULL to let the system allocate one. The mode specifies how the buffer is used.
Inputs
stream - Pointer to a valid FILE object. buf - User-provided buffer (or NULL for system-allocated). mode - One of _IOFBF (full), _IOLBF (line), _IONBF (none). size - Size of the buffer (must meet platform-specific minimum if buf is not NULL).
Result
Returns 0 on success, or EOF (-1) on failure. If an error occurs, `errno` is set to indicate the cause (e.g., EFAULT, EINVAL, EBADF).
Example
FILE *fp = fopen("example.txt", "w");
char buffer[512];
if (setvbuf(fp, buffer, _IOFBF, sizeof(buffer)) != 0)
{
perror("Failed to set buffer");
}
Notes
- This function must be called before any stream I/O. - Supplying a buffer smaller than the platform minimum will result in an error. - Mode must be a valid constant (_IOFBF, _IOLBF, or _IONBF). - If `size` is 0, the system will determine an appropriate buffer size.
Bugs
- No runtime check ensures that the stream hasn't already been used. - The required minimum buffer size (208 bytes) is AROS-specific and may not match other platforms' expectations.
sigaction()
Synopsis
int sigaction( int signum, const struct sigaction *act, struct sigaction *oldact)
Function
Examine and change a signal action.
Inputs
signum - signal number to examine/change (must not be SIGKILL or
SIGSTOP)
act - if non-NULL, set the signal action to this value
oldact - if non-NULL, store the previous signal action here
Result
0 on success, -1 on error with errno set.
Notes
Supported sa_flags: SA_SIGINFO, SA_RESETHAND, SA_NODEFER, SA_RESTART. SA_ONSTACK, SA_NOCLDSTOP, SA_NOCLDWAIT are accepted but have no effect since AROS does not deliver asynchronous signals.
See also
sigaddset()
Synopsis
int sigaddset( sigset_t *set, int signum)
sigdelset()
Synopsis
int sigdelset( sigset_t *set, int signum)
sigemptyset()
Synopsis
int sigemptyset( sigset_t *set)
sigfillset()
Synopsis
int sigfillset( sigset_t *set)
Function
Initialise the signal set
Inputs
Set to initialize
Result
"0" for success, "-1" for failure (errno contains error)
sigismember()
Synopsis
int sigismember( const sigset_t *set, int signum)
siglongjmp()
Synopsis
void siglongjmp( jmp_buf env, int val)
Function
Save the current context so that you can return to it later.
Inputs
env - The context/environment to restore
val - This value is returned by setjmp() when you return to the
saved context. You cannot return 0. If val is 0, then
setjmp() returns with 1.
Result
This function doesn't return.
Example
jmp_buf env;
... some code ...
if (!setjmp (env))
{
... this code is executed after setjmp() returns ...
// This is no good example on how to use this function
// You should not do that
if (error)
siglongjmp (env, 5);
... some code ...
}
else
{
... this code is executed if you call siglongjmp(env) ...
}
See also
stdc/setjmp()
sigpending()
Synopsis
int sigpending( sigset_t *set)
Function
Return the set of signals that are pending for delivery.
Inputs
set - receives the set of pending signals
Result
0 on success, -1 on error with errno set.
Notes
Since AROS does not deliver asynchronous signals, the pending set is always empty.
See also
sigprocmask()
Synopsis
int sigprocmask( int how, const sigset_t *set, sigset_t *oldset)
Function
Examine or change the signal mask of the calling thread.
Inputs
how - how to change the mask: SIG_BLOCK, SIG_UNBLOCK, or
SIG_SETMASK
set - if non-NULL, the set of signals to apply according to 'how'
oldset - if non-NULL, receives the previous signal mask
Result
0 on success, -1 on error with errno set.
Notes
Since AROS does not deliver asynchronous signals the mask only affects what raise() would do if checked.
See also
sigsetjmp()
Synopsis
int sigsetjmp( sigjmp_buf env, int val)
Function
Save a calling environment for a later return with siglongjmp().
Inputs
env - Writable sigjmp_buf object with its declared alignment. Keep it
intact and alive while a later jump can use it.
val - Signal-mask save request, conventionally named savemask.
Currently ignored, including when nonzero.
Result
Zero initially. After siglongjmp(), the value supplied to that call, with zero replaced by 1.
Notes
Include <setjmp.h>. Pair this call with siglongjmp(), not longjmp(). The lifetime, thread, expression and local-variable restrictions of stdc/setjmp() also apply. This call saves CPU context, not a copy of program memory or resource ownership.
Bugs
The AROS implementations do not save a signal mask, and siglongjmp() does not restore one. A nonzero val therefore does not provide the POSIX signal-mask preservation contract. Do not use this pair where correctness depends on restoring the mask after a jump.
See also
siglongjmp() stdc/setjmp() stdc/longjmp()
sigsuspend()
Synopsis
int sigsuspend( const sigset_t *mask)
Function
Replace the callers signal mask temporarily, and suspend the process until a signal is delivered that either terminates it or invokes a signal handler.
Inputs
mask - the temporary signal mask to use while suspended
Result
Always returns -1 with errno set to EINTR (successful return after a signal handler) or EFAULT (bad pointer).
Notes
AROS has no asynchronous POSIX signal delivery. To still provide a genuine suspend (rather than returning immediately), this blocks on the task's CTRL-C break signal and translates a received break into SIGINT when SIGINT is not blocked by the temporary mask.
See also
sleep()
Synopsis
unsigned int sleep( unsigned int seconds )
Function
The sleep() function makes the current process sleep for the specified number of seconds or until a signal arrives which is not ignored.
Inputs
seconds - The number of seconds to sleep
Result
Zero if the requested time has elapsed, or the number of seconds left to sleep when the process was signaled.
Example
// Sleep for 10 seconds sleep( 10 );
Bugs
The current implementation simply uses the dos.library function Delay() to sleep, and cannot be interrupted by incoming signals. This shouldn't be of any importance, since AROS doesn't have POSIX style signaling yet (but when it is implemented, this function needs to be changed).
srand48()
Synopsis
void srand48( long seed)
stat()
Synopsis
int stat( const char *path, struct stat *sb)
Function
Returns information about a file. Information is stored in stat
structure having the following fields:
dev_t st_dev; - ID of device containing the file
ino_t st_ino; - inode number
mode_t st_mode; - protection mode
nlink_t st_nlink; - number of hard links
uid_t st_uid; - user ID of the file's owner
gid_t st_gid; - group ID of the file's group
dev_t st_rdev; - device ID (if the file is character
or block special file)
off_t st_size; - file size, in bytes
time_t st_atime; - time of last access
time_t st_mtime; - time of last data modification
time_t st_ctime; - time of last file status change
blksize_t st_blksize; - optimal blocksize for I/O
blkcnt_t st_blocks; - number of blocks allocated for file
Inputs
path - Pathname of the file sb - Pointer to stat structure that will be filled by the stat() call.
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
See also
stat64()
Synopsis
int stat64( const char *path, struct stat64 *sb)
Function
Returns information about a file. Information is stored in stat
structure having the following fields:
dev_t st_dev; - ID of device containing the file
ino64_t st_ino; - (lfs) inode number
mode_t st_mode; - protection mode
nlink_t st_nlink; - number of hard links
uid_t st_uid; - user ID of the file's owner
gid_t st_gid; - group ID of the file's group
dev_t st_rdev; - device ID (if the file is character
or block special file)
off64_t st_size; - (lfs) file size, in bytes
time_t st_atime; - time of last access
time_t st_mtime; - time of last data modification
time_t st_ctime; - time of last file status change
blksize_t st_blksize; - optimal blocksize for I/O
blkcnt64_t st_blocks; - (lfs) number of blocks allocated for file
Inputs
path - Pathname of the file sb - Pointer to stat structure that will be filled by the stat() call.
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
statfs()
Synopsis
int statfs( const char *path, struct statfs *buf)
Function
Gets information about mounted filesystem.
Inputs
path - path to any file in the filesystem we want to know about
buf - pointer to statfs structures where information about filesystem
will be stored
Result
Information about filesystem is stored in statfs structure
Bugs
f_flags, f_files, f_ffree and f_fsid.val are always set to 0 f_mntfromname is set to an empty string
statvfs()
Synopsis
int statvfs( const char *restrict path, struct statvfs *restrict buf)
Function
Read block usage for the volume containing a file or directory.
Inputs
path - Null-terminated AROS pathname of an existing file
or directory. Passed directly to dos.library/Lock();
POSIX pathname translation is not performed.
buf - Writable, caller-owned struct statvfs storage. The
pathname must not overlap this storage.
Result
0 on success; -1 on failure with errno set as follows: EINVAL - path or buf is NULL; the buffer is unchanged. ENOENT - The pathname could not be locked. EIO - The volume-information query failed. For ENOENT or EIO, the entire result buffer is zeroed.
Notes
Include <sys/statvfs.h>. On success, f_bsize and f_frsize contain bytes per block; f_blocks contains total blocks; f_bfree contains total blocks minus used blocks; and f_bavail equals f_bfree. f_files, f_ffree, f_favail, f_fsid and f_flag are zero. f_namemax is always 31. These fields are placeholders, not queried filesystem limits, identifiers or mount flags. The call may wait for DOS pathname resolution and volume queries. Its temporary lock is released before returning.
Bugs
All Lock() failures become ENOENT, including failures unrelated to a missing file. Volume-query errors become EIO without preserving their specific cause in errno. Block-count precision depends on the filesystem query and the compiled result types. Narrowing and inconsistent used-block counts are not checked; no EOVERFLOW error is reported. Zero f_flag does not establish writability, and f_bavail does not account for per-user restrictions.
strcoll_l()
Synopsis
int strcoll_l( const char *s1, const char *s2, locale_t loc)
Function
Compare two null-terminated strings in unsigned-byte order. Comparison stops at the first differing byte or the terminating null byte.
Inputs
s1 - First readable, null-terminated string. s2 - Second readable, null-terminated string. loc - Ignored; neither dereferenced nor retained. Neither string pointer may be NULL. The strings may overlap; their contents are not modified.
Result
A negative value if s1 precedes s2, zero if they are equal, or a positive value if s1 follows s2. The result is not limited to -1, 0 and 1. errno is unchanged.
Notes
Include <string.h>. The comparison allocates no storage and does not retain either string.
Bugs
Locale-specific collation is not implemented. The supplied locale and current locale do not affect the result. Multibyte characters are compared as individual bytes; no linguistic ordering or normalization is performed.
See also
strerror()
Synopsis
char * strerror( int n)
Function
Returns a readable string for an error number in errno.
Inputs
n - The contents of errno or a #define from errno.h
Result
A string describing the error.
Notes
This function is used to override the strerror() function of stdc.library to handle the extra errnos from posixc.library.
strerror_r()
Synopsis
int strerror_r( int errnum, char *buf, size_t buflen)
Function
Copies a string describing the error code 'errnum' into the buffer 'buf', ensuring the string is null-terminated. This function is a thread-safe and reentrant alternative to strerror(). It looks up the error message for 'errnum' from the system-defined list of error strings, including POSIX-specific error numbers handled by the AROS POSIXC library. If the error number is not recognized, a fallback string is provided by __stdc_strerror(), or "Unknown error" if that fails.
Inputs
errnum - the error code to look up (usually errno). buf - a pointer to the buffer where the error message will be stored. buflen - the size of the buffer in bytes.
Result
0 - success, message copied to 'buf'. ERANGE - buffer too small; message was truncated but is null-terminated. Other errno values may be returned for invalid parameters.
Example
char buf[64];
if (strerror_r(errno, buf, sizeof(buf)) != 0)
strcpy(buf, "Unknown error");
printf("Error: %s\n", buf);
Notes
The string written to 'buf' will be null-terminated. If 'buflen' is 0, no message is written and ERANGE is returned. This is the POSIX-compliant variant of strerror_r(), returning an int.
Bugs
The fallback to __stdc_strerror() may return NULL for unknown codes, in which case a generic "Unknown error" message is used. Buffer truncation is not distinguishable from other ERANGE cases.
See also
strftime_l()
Synopsis
size_t strftime_l(
char *restrict buf, size_t maxsize,
const char *restrict format,
const struct tm *restrict tm,
locale_t locale)
Function
Converts the time information in the struct tm pointed to by 'tm' into a formatted string according to the 'format' specification and the specified 'locale'. The resulting string is placed in the buffer pointed to by 'buf', which can contain up to 'maxsize' characters, including the terminating null.
Inputs
buf - Pointer to the destination character buffer.
maxsize - Maximum number of characters to store in the destination,
including the null terminator.
format - Format control string containing ordinary characters and
conversion specifiers, similar to ANSI strftime().
tm - Pointer to a struct tm containing the time values to format.
locale - The locale to use for localized string lookups. If NULL,
the current process or system default locale is used.
Result
The number of characters written to the destination buffer, excluding the terminating null character. Returns 0 if an error occurs (e.g., invalid arguments or formatting failure).
Example
struct tm now = { .tm_year = 124, .tm_mon = 6, .tm_mday = 7, .tm_wday = 0,
.tm_hour = 15, .tm_min = 30, .tm_sec = 45 };
char buf[64];
strftime_l(buf, sizeof(buf), "%A, %B %d, %Y %H:%M:%S %p", &now, NULL);
// Example output: "Sunday, July 07, 2024 15:30:45 PM"
Notes
Supports a subset of ANSI C strftime() specifiers: %a %A - abbreviated and full weekday names %b %B - abbreviated and full month names %p - AM/PM indicator %d %m %y %Y %H %I %M %S - numeric date/time fields %n %t %% - special characters Composite formats (%c, %x, %X, etc.) and locale-specific date/time formats are not yet implemented.
Bugs
- Does not support all strftime() specifiers. - Locale argument may be ignored if only a global locale is supported.
See also
strptime()
Synopsis
char * strptime( const char *s, const char *format, struct tm *tm)
Function
Parse selected numeric date and time fields from s into existing struct tm storage. Fields are updated as they are encountered; the structure is not initialized.
Inputs
s - Readable, null-terminated input string.
format - Readable, null-terminated format string. Supported
conversions are %d, %e, %H, %m, %M, %S, %w, %y,
%Y and %%. Other conversions are unsupported.
tm - Writable result structure, separate from both strings.
Initialize fields that the format does not supply.
Result
A pointer into s after the parsed portion, or NULL on a reported failure. Trailing input need not be consumed. If any argument is NULL, returns NULL with errno set to EINVAL before modifying the result. On later failure, earlier field assignments remain. Other failures do not have a defined errno value. Because of the parser defects below, a non-NULL result does not establish that the input matched or represents a valid date.
Notes
Include <time.h>. %d and %e assign tm_mday; %H assigns tm_hour; %m assigns the parsed month minus one to tm_mon; %M assigns tm_min; %S assigns tm_sec; and %w assigns tm_wday. %y assigns tm_year directly, while %Y subtracts 1900. No century window is applied to %y. Format whitespace matches zero or more input whitespace characters. Other ordinary characters must match exactly. Numeric fields use decimal scanning without field-width limits. Unspecified fields, including tm_yday and tm_isdst, remain unchanged; no derived fields are computed.
Bugs
Numeric parsing accepts a failed zero-conversion scan as success and can assign an uninitialized or previous value. It also passes int storage to an unsigned scanf conversion, violating that conversion's argument-type contract. A failed %% match moves the input pointer backwards instead of reporting failure, potentially outside the input object. A trailing % in format is silently accepted. Field ranges, arithmetic overflow and calendar consistency are not checked. Names, locale-specific formats, time zones and all unlisted conversions are unsupported.
See also
strtod_l()
Synopsis
double strtod_l( const char * restrict nptr, char ** restrict endptr, locale_t loc)
Function
Convert the initial decimal floating-point number in nptr. Leading whitespace and an optional sign are accepted. The decimal separator is a period; e or E introduces an optional signed decimal exponent.
Inputs
nptr - Readable, null-terminated string; must not be NULL.
endptr - Optional pointer to writable pointer storage,
separate from the input string. May be NULL.
loc - Ignored; neither dereferenced nor retained.
Result
The converted value. If endptr is supplied, *endptr points to the first unconverted character. If no conversion is performed, returns zero and stores nptr in *endptr. An exponent with no digits is left unconsumed. Case-insensitive inf, infinity and nan are accepted. A parenthesized NaN suffix is consumed only if it contains alphanumeric characters or underscores and has a closing parenthesis; an empty suffix is also accepted. The suffix does not select the NaN payload.
Notes
Include <stdlib.h> with _GNU_SOURCE defined, _XOPEN_SOURCE >= 700, or _POSIX_C_SOURCE >= 200809L. The first call through this function instance emits a debug diagnostic that the locale argument is ignored.
Bugs
The supplied locale has no effect. Hexadecimal floating- point notation is unsupported: parsing 0x1p0 stops at x. Conversion uses double arithmetic without a correctly rounded conversion algorithm. Range-error reporting is incomplete; errno alone cannot establish a valid result. Large exponents can overflow an unchecked int accumulator. Intermediate overflow or underflow can corrupt a result even when the mathematical value is representable.
See also
strtof_l()
Synopsis
float strtof_l( const char * restrict nptr, char ** restrict endptr, locale_t loc)
Function
Convert the initial decimal floating-point number in nptr. Leading whitespace and an optional sign are accepted. The decimal separator is a period; e or E introduces an optional signed decimal exponent.
Inputs
nptr - Readable, null-terminated string; must not be NULL.
endptr - Optional pointer to writable pointer storage,
separate from the input string. May be NULL.
loc - Ignored; neither dereferenced nor retained.
Result
The converted value. If endptr is supplied, *endptr points to the first unconverted character. If no conversion is performed, returns zero and stores nptr in *endptr. An exponent with no digits is left unconsumed. Case-insensitive inf, infinity and nan are accepted. A parenthesized NaN suffix is consumed only if it contains alphanumeric characters or underscores and has a closing parenthesis; an empty suffix is also accepted. The suffix does not select the NaN payload.
Notes
Include <stdlib.h> with _GNU_SOURCE defined, _XOPEN_SOURCE >= 700, or _POSIX_C_SOURCE >= 200809L. The first call through this function instance emits a debug diagnostic that the locale argument is ignored.
Bugs
The supplied locale has no effect. Hexadecimal floating- point notation is unsupported: parsing 0x1p0 stops at x. Conversion uses double arithmetic without a correctly rounded conversion algorithm. Range-error reporting is incomplete; errno alone cannot establish a valid result. Large exponents can overflow an unchecked int accumulator. Intermediate overflow or underflow can corrupt a result even when the mathematical value is representable. The double result is converted to float without checking the narrower range. Additional rounding, overflow or underflow is not reported by this wrapper.
See also
strtok_r()
Synopsis
char * strtok_r( char * str, const char * sep, char **saveptr)
Function
Separates a string by the characters in sep.
Inputs
str - The string to check or NULL if the next word in
the last string is to be searched.
sep - Characters which separate "words" in str.
saveptr - internal context for next scan
Result
The first word in str or the next one if str is NULL.
Example
char buffer[64]; char *ptr; strcpy (buffer, "Hello, this is a test."); // Init. Returns "Hello" strtok_r (str, " \t,.", &ptr); // Next word. Returns "this" strtok_r (NULL, " \t,.", &ptr); // Next word. Returns "is" strtok_r (NULL, " \t", &ptr); // Next word. Returns "a" strtok_r (NULL, " \t", &ptr); // Next word. Returns "test." strtok_r (NULL, " \t", &ptr); // Next word. Returns NULL. strtok_r (NULL, " \t", &ptr);
Notes
The function changes str !
strtold_l()
Synopsis
long double strtold_l( const char * restrict nptr, char ** restrict endptr, locale_t loc)
Function
Convert the initial decimal floating-point number in nptr. Leading whitespace and an optional sign are accepted. The decimal separator is a period; e or E introduces an optional signed decimal exponent.
Inputs
nptr - Readable, null-terminated string; must not be NULL.
endptr - Optional pointer to writable pointer storage,
separate from the input string. May be NULL.
loc - Ignored; neither dereferenced nor retained.
Result
The converted value. If endptr is supplied, *endptr points to the first unconverted character. If no conversion is performed, returns zero and stores nptr in *endptr. An exponent with no digits is left unconsumed. Case-insensitive inf, infinity and nan are accepted. A parenthesized NaN suffix is consumed only if it contains alphanumeric characters or underscores and has a closing parenthesis; an empty suffix is also accepted. The suffix does not select the NaN payload.
Notes
Include <stdlib.h> with _GNU_SOURCE defined, _XOPEN_SOURCE >= 700, or _POSIX_C_SOURCE >= 200809L. The first call through this function instance emits a debug diagnostic that the locale argument is ignored.
Bugs
The supplied locale has no effect. Hexadecimal floating- point notation is unsupported: parsing 0x1p0 stops at x. Conversion uses double arithmetic without a correctly rounded conversion algorithm. Range-error reporting is incomplete; errno alone cannot establish a valid result. Large exponents can overflow an unchecked int accumulator. Intermediate overflow or underflow can corrupt a result even when the mathematical value is representable. The double result is widened to long double. This does not provide the additional range or precision of a wider long double format.
See also
strtoll_l()
Synopsis
long long strtoll_l( const char * restrict nptr, char ** restrict endptr, int base, locale_t loc)
Function
Convert the initial integer in nptr using the specified base. Leading whitespace and one optional sign are accepted. Conversion stops at the first invalid digit.
Inputs
nptr - Readable, null-terminated string; must not be NULL.
endptr - Optional pointer to writable pointer storage,
separate from the input string. May be NULL.
base - 0 to select octal for a leading zero, hexadecimal
for 0x or 0X followed by a hexadecimal digit, and
decimal otherwise; or an explicit base from 2 to 36.
Base 16 also accepts the hexadecimal prefix.
loc - Ignored; neither dereferenced nor retained.
Result
The converted value. If endptr is non-NULL, *endptr points to the first unconverted character. If no digits are converted, returns 0 and stores nptr in *endptr. An invalid base returns 0, sets errno to EINVAL and stores nptr in *endptr when supplied. Range errors set ERANGE; scanning continues through all remaining valid digits. Successful conversion does not clear errno. Values outside the signed range return LLONG_MIN or LLONG_MAX, according to the sign.
Notes
Include <stdlib.h> with _GNU_SOURCE defined, _XOPEN_SOURCE >= 700, or _POSIX_C_SOURCE >= 200809L. Letters A through Z and a through z represent digits 10 through 35. No binary 0b prefix is recognized. The first call through this function instance emits a debug diagnostic that the locale argument is ignored. Subsequent calls suppress that diagnostic.
Bugs
The supplied locale does not affect conversion.
See also
strtoull_l()
Synopsis
unsigned long long strtoull_l( const char * restrict nptr, char ** restrict endptr, int base, locale_t loc)
Function
Convert the initial integer in nptr using the specified base. Leading whitespace and one optional sign are accepted. Conversion stops at the first invalid digit.
Inputs
nptr - Readable, null-terminated string; must not be NULL.
endptr - Optional pointer to writable pointer storage,
separate from the input string. May be NULL.
base - 0 to select octal for a leading zero, hexadecimal
for 0x or 0X followed by a hexadecimal digit, and
decimal otherwise; or an explicit base from 2 to 36.
Base 16 also accepts the hexadecimal prefix.
loc - Ignored; neither dereferenced nor retained.
Result
The converted value. If endptr is non-NULL, *endptr points to the first unconverted character. If no digits are converted, returns 0 and stores nptr in *endptr. An invalid base returns 0, sets errno to EINVAL and stores nptr in *endptr when supplied. Range errors set ERANGE; scanning continues through all remaining valid digits. Successful conversion does not clear errno. A minus sign negates the converted magnitude in unsigned arithmetic. A positive overflow returns ULLONG_MAX.
Notes
Include <stdlib.h> with _GNU_SOURCE defined, _XOPEN_SOURCE >= 700, or _POSIX_C_SOURCE >= 200809L. Letters A through Z and a through z represent digits 10 through 35. No binary 0b prefix is recognized. The first call through this function instance emits a debug diagnostic that the locale argument is ignored. Subsequent calls suppress that diagnostic.
Bugs
The supplied locale does not affect conversion. A negative input whose magnitude exceeds ULLONG_MAX returns 1 instead of ULLONG_MAX, with errno set to ERANGE. The overflow result is incorrectly negated.
See also
strxfrm_l()
Synopsis
size_t strxfrm_l( char *dest, const char *src, size_t n, locale_t loc)
Function
Copy a byte string as a C-locale collation key.
Inputs
dest - Destination buffer with room for n bytes; may be
NULL when n is zero. It must not overlap src.
src - Readable null-terminated byte string, including when
n is zero.
n - Destination capacity in bytes.
loc - Ignored; no locale data is read.
Result
The length of src in bytes, excluding its null terminator. A return value less than n indicates a complete key. Otherwise, the destination must not be used as a complete null-terminated key.
Notes
Include <string.h>. No storage is allocated. With n equal to zero, the function measures src without writing dest. Otherwise it copies up to n bytes and pads unused bytes with zeros. If the source length is at least n, no null terminator is written. Neither input pointer is retained.
Bugs
Locale-specific collation is not implemented. The function uses strxfrm() and ignores loc.
See also
swab()
Synopsis
void swab( const void *from, void *to, size_t len)
symlink()
Synopsis
int symlink( const char *oldpath, const char *newpath)
sync()
Synopsis
void sync( )
Function
Return without performing any synchronization. This function is not implemented.
Result
No return value. errno is unchanged.
Notes
Include <unistd.h>. The call issues no filesystem or device requests and does not wait for pending writes.
Bugs
The call does not flush buffered data or metadata. Its return provides no guarantee that changes have reached storage, and no error or diagnostic reports this limitation.
sysconf()
Synopsis
long sysconf( int name)
Notes
Only _SC_ARG_MAX, _SC_PAGESIZE/_SC_PAGE_SIZE, _SC_CLK_TCK and the _SC_PHYS_PAGES, _SC_NPROCESSORS_CONF and _SC_NPROCESSORS_ONLN extensions are implemented; other names fail with EINVAL.
system()
Synopsis
int system( const char *string)
Function
Executes a command specified by the string argument. If the string is `NULL`, the function returns 1 to indicate that a command processor is available. If the string is non-NULL, the command is passed to a shell (if available) or executed directly if no shell is present.
Inputs
string - Command string to execute, or NULL to check for shell support.
Result
On success, returns the command's exit status. On error, returns -1 and sets `errno` appropriately. If `string` is NULL, returns 1 (indicating a shell is available).
Example
system("ls -l /");
Notes
- On AROS, if the environment supports it, the command will be executed through `/bin/sh` (or `bin:sh`). - If no shell is found, the command is executed directly using the AROS `SystemTags()` interface. - The implementation ensures standard input/output/error are passed through to the new process. - Command paths and arguments are translated from UNIX-style to Amiga-style if necessary.
Bugs
- Argument splitting and quoting are simplistic; edge cases may break. - Behavior depends on the shell being available in `bin:sh`.
tcgetattr()
Synopsis
int tcgetattr( int fd, struct termios *t)
Function
Get terminal attributes.
Inputs
fd - file descriptor t - struct termios where attributes are put
Result
0 - success -1 - error
Notes
Currently supports only ICANON flag
See also
tcgetpgrp()
Synopsis
pid_t tcgetpgrp( int fd)
Function
Returns the process group ID for the specified file descriptor.
tcsetattr()
Synopsis
int tcsetattr( int fd, int opt, const struct termios *t)
Function
Set terminal attributes.
Inputs
fd - file descriptor opt - optional actions t - struct termios containing the requested changes
Result
0 - success -1 - error
Notes
Currently supports only ICANON. For compatibility, TCSANOW, TCSADRAIN and TCSAFLUSH all apply the mode immediately. Output drain and input flush are not implemented; accepting these actions does not provide their full POSIX semantics.
See also
telldir()
Synopsis
long telldir( DIR *dir)
tempnam()
Synopsis
char * tempnam( const char *dir, const char *pfx)
times()
Synopsis
clock_t times( struct tms *tms)
Notes
Not implemented.
tmpfile()
Synopsis
FILE * tmpfile( void)
Function
The tmpfile() function returns a pointer to a stream associated with a file descriptor returned by the routine mkstemp(3). The created file is unlinked before tmpfile() returns, causing the file to be automatically deleted when the last reference to it is closed. The file is opened with the access value `w+'. The file is created in the T: directory, which is the standard AROS temp directory.
Result
The tmpfile() function returns a pointer to an open file stream on
success. On error, a NULL pointer is returned and errno is set
appropriately.
ERRORS
The tmpfile() function may fail and set the global variable
errno for any of the errors specified for the library functions
fdopen() or mkstemp().
Example
#include <errno.h>
#include <stdio.h>
#include <string.h>
main()
{
FILE * fp;
fp = tmpfile();
if ( fp == NULL)
{
perror(strerror(errno));
return;
}
fprintf(fp, "do a bit of writing to the temp file");
}
Bugs
BUG1: The temporary file is neither closed nor deleted. Ideally, unlink() could be used to mark the temp file for removal (see BUG1 in the source code) - but I suspect a bug in unlink() itself, whereby it tries to remove the file straight away, rather than waiting for all references to it to be closed. The bug is not too serious, because all temp files are written to the T: directory, which get zapped when AROS is closed down. However, problems may exist when you start creating over 26 temp files with the same PID.
tmpnam()
Synopsis
char *tmpnam( char *s)
Function
Generates a string that is a valid and unique filename for a temporary file. The filename is not associated with an open file and is not guaranteed to remain unique if used multiple times without creating the file immediately.
Inputs
s - Optional pointer to a user-provided buffer. If NULL, a static internal
buffer is used. The buffer must be at least L_tmpnam bytes in size.
Result
Returns a pointer to the generated filename (either `s` or internal static buffer), or NULL if an error occurs.
Example
char name[L_tmpnam];
if (tmpnam(name) != NULL) {
printf("Temporary file name: %s\n", name);
}
Notes
- The generated name is not guaranteed to be safe against race conditions; use `tmpfile()` or `mkstemp()` for safer temporary file handling. - If called multiple times with NULL, the static buffer is reused and may be overwritten by subsequent calls. - On AROS, the filename is formed using the `P_tmpdir` macro and a counter. - `_mktemp()` is used to finalize the name in-place by replacing `XXXXXX`.
Bugs
- Not thread-safe when `s == NULL`, due to use of a static buffer. - The `_mktemp()` function is inherently unsafe; it does not create the file, which can lead to race conditions if multiple processes or threads are involved. - May return the same name if not followed by immediate file creation.
towlower_l()
Synopsis
wint_t towlower_l( wint_t wc, locale_t locale)
See also
towupper_l()
Synopsis
wint_t towupper_l( wint_t wc, locale_t locale)
Function
Converts a lowercase wide character to its uppercase equivalent.
Inputs
wc - a wide character code point.
Result
The uppercase equivalent of the input character if applicable; otherwise returns the character unchanged.
Example
wint_t c = towupper(L'è'); // returns L'È'
Notes
Supports all characters in the ASCII and Latin-1 Supplement ranges. For example, `L'ö'` ? `L'Ö'`.
Bugs
Characters outside U+00FF are returned unchanged.
See also
truncate()
Synopsis
int truncate( const char *path, off_t length)
Function
Truncate a file to a specified length
Inputs
path - the path of the file being truncated lenght - The file will have at most this size
Result
0 on success or -1 on errorr.
Notes
If the file previously was larger than this size, the extra data is lost. If the file previously was shorter, it is unspecified whether the file is left unchanged or is extended. In the latter case the extended part reads as zero bytes.
See also
ttyname()
Synopsis
char * ttyname( int fd)
Notes
Not implemented.
tzset()
Synopsis
void tzset( void)
Function
Initialise the timezone conversion information used by localtime() and related functions from the TZ environment variable, and set the global variables timezone, daylight and tzname accordingly.
Inputs
None.
Result
None. The external variables are set as follows:
timezone - The difference, in seconds, between Coordinated Universal
Time (UTC) and local standard time (positive West of UTC).
daylight - Non-zero if the TZ value names a daylight-saving timezone.
tzname - tzname[0] is the abbreviation of the standard timezone,
tzname[1] that of the daylight-saving timezone.
Example
setenv("TZ", "EST5EDT", 1);
tzset();
// timezone == 5*3600, daylight != 0, tzname[0] == "EST"
Notes
Only the POSIX "std offset[dst[offset]][,rule]" form of TZ is recognised, and the optional daylight-saving offset and transition rules are not applied (AROS keeps no timezone-rule database, so daylight-saving time is never actually entered). When TZ is unset the offset is taken from the system locale and the abbreviations default to "UTC".
umask()
Synopsis
mode_t umask( mode_t numask)
Notes
umask is currently remembered but not used in any function
uname()
Synopsis
int uname( struct utsname *name)
Function
Store information about the operating system in the structure pointed to by name.
Inputs
name - Pointer to utsname structure defined in <sys/utsname.h>.
Result
If the information was stored successfully, zero is returned. Otherwise function returns -1 and sets errno appropriately.
ungetc()
Synopsis
int ungetc( int c, FILE * stream)
Function
Push the character c character back into the stream.
Inputs
c - Put this character back into the stream. The next read will
return this character. If you push back more than one
character, then they will be returned in reverse order.
The function guarantees that one character can be
pushed back but no more. It is possible to push the EOF
character back into the stream.
stream - Read from this stream
Result
c or EOF on error.
unlink()
Synopsis
int unlink( const char * pathname)
Function
Delete a file from disk.
Inputs
pathname - Complete path to the file
Result
0 on success and -1 on error. In case of an error, errno is set.
Example
// Delete the file xyz in the current directory
unlink ("xyz");
Notes
Identical to remove
See also
unlinkat()
Synopsis
int unlinkat( int dirfd, const char *pathname, int flags)
Function
Like unlink() (or rmdir() when AT_REMOVEDIR is given), but a relative pathname is resolved against the directory referenced by dirfd instead of the current directory.
Inputs
dirfd - descriptor of an open directory, or AT_FDCWD pathname - entry to remove flags - 0 or AT_REMOVEDIR
Result
0 on success, -1 with errno set on failure.
unsetenv()
Synopsis
int unsetenv( const char *name)
Function
deletes a variable from the environment.
Inputs
name -- Name of the environment variable to delete.
Result
Returns zero on success, or -1 if the variable was not found.
updatestdio()
Synopsis
void updatestdio( void)
Function
Update stdin, stdout, stderr to reflect changes done by calling dos.library functions like SelectInput(), ...
Inputs
-
Result
-
Notes
stdin, stdout and stderr will be flushed before they are updated.
uselocale()
Synopsis
locale_t uselocale( locale_t newloc)
Function
Return a locale handle without changing the active locale.
Inputs
newloc - Value to return. The argument is not inspected,
dereferenced or retained.
Result
newloc unchanged. In particular, a zero argument returns zero and LC_GLOBAL_LOCALE returns LC_GLOBAL_LOCALE. The function does not change errno.
Notes
Include <locale.h>. No storage is allocated or released.
Bugs
Per-thread locale selection is not implemented. This function neither installs newloc nor returns the previous locale. Passing zero does not query the active locale. Its return value cannot be used to save and restore locale state, and does not indicate that a locale was accepted.
See also
usleep()
Synopsis
int usleep( useconds_t usec)
Function
Suspends program execution for a given number of microseconds.
Inputs
usec - number of microseconds to wait
Result
0 on success, -1 on error
Notes
This function is not part of POSIX.1-2008 anymore. Don't use this function. As an alternative nanosleep() can be used.
See also
utime()
Synopsis
int utime( const char *filename, const struct utimbuf *buf)
Function
Change last access and last modification time of the given file to times specified in given utimbuf structure. If buf is NULL, the current time will be used instead. The utimbuf structure contains of two fields: time_t actime; - last access time time_t modtime; - last modification time
Inputs
filename - Name of the file buf - Pointer to utimbuf structure describing specified time.
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
Notes
This function can be used to set access and modification times with a resolution of 1 second, use utimes() if you need better precision.
Bugs
Since AROS has no notion of last access time, actime field is silently ignored, only modification time of the file is set.
See also
utimes()
Synopsis
int utimes( const char *file, const struct timeval tvp[2])
Function
Change last access and last modification time of the given file to times specified in tvp array. If tvp is NULL, the current time will be used instead.
Inputs
filename - Name of the file
buf - Pointer to an array of two timeval structures. First structure
specifies the last access time, second specifies the last
modification time
Result
0 on success and -1 on error. If an error occurred, the global variable errno is set.
Notes
The timeval structure has microsecond resolution, but in reality this function has time resolution of 1 tick.
Bugs
Since AROS has no notion of last access time, it's silently ignored and only modification time of the file is set.
See also
vdprintf()
Synopsis
int vdprintf( int fd, const char * restrict format, va_list args)
Function
Format output according to format and write it to the file descriptor fd. Equivalent to vfprintf() but operating on a POSIX file descriptor rather than a FILE stream.
Inputs
fd - the file descriptor to write to. format - printf()-style format string. args - the variable argument list.
Result
The number of bytes written, or a negative value on error.
See also
vfork()
Synopsis
pid_t vfork( void)
Function
Function to create a subprocess of the current process. This is there to ease porting of software using the fork()/vfork() POSIX functions. Due to a different memory and process model, fork() is not implemented at the moment in the C library. vfork() is provided with some extended functionality. In the POSIX standard the only guaranteed functionality for vfork() is to have an exec*() function or exit() called right after the vfork() in the child. Extra functionality for vfork(): - The child has its own memory heap; memory allocation/deallocation is allowed and the heap will be removed when calling _exit() or will be used for the code started by the exec*() functions. - The child will have a copy of the file descriptors as specified by the POSIX standard for the fork() function. File I/O is possible in the child, as is file manipulation with dup() etc. Difference with fork(): - The virtual memory heap is not duplicated as in POSIX but the memory is shared between parent and child. AROS lives in one big single memory region so changes to memory in the child are also seen by the parent. Behavior for other resources not described in this doc may not be relied on for future compatibility.
Inputs
-
Result
-1: error, no child is started; errno will be set. 0: Running in child >0: Running in parent, pid of child is return value.
Notes
Current implementation of vfork() will only really start running things in parallel on an exec*() call. After vfork(), child code will run until _exit() or exec*(). With _exit(), the child will exit and the parent will continue; with exec*(), the child will be detached and the parent will continue.
vfprintf()
Synopsis
int vfprintf( FILE * stream, const char * format, va_list args)
Function
Writes formatted output to the specified output stream using the format string and a `va_list` of arguments.
Inputs
stream - A pointer to an open output stream. format - A format string, as used in printf(). args - A `va_list` of arguments to be formatted and printed.
Result
Returns the number of characters written, or 0 if an error occurred (e.g., invalid stream).
Example
va_list ap; va_start(ap, fmt); vfprintf(stdout, fmt, ap); va_end(ap);
Notes
- The stream must be writable and valid. - This function is typically called by `fprintf` and `printf` internally. - Format specifiers follow standard printf-style conventions.
Bugs
- Returns 0 instead of the standard -1 on error, which may cause incorrect error checking by compliant code. - Not thread-safe if stream is shared among threads without synchronization. - Assumes AROS-specific file descriptor abstraction and output handling.
vfscanf()
Synopsis
int vfscanf( FILE * stream, const char * format, va_list args)
Function
Reads input from the specified stream, interprets it according to the provided format string, and stores the results in the locations pointed to by the variable argument list `args`.
Inputs
stream - A pointer to a readable input stream.
format - A scanf-style format string describing expected input format.
args - A `va_list` containing pointers to the variables where
the results of the formatted input will be stored.
Result
Returns the number of input items successfully matched and assigned, which may be fewer than provided for, or zero in the event of an early matching failure. Returns 0 if the stream is invalid.
Example
va_list ap; va_start(ap, fmt); vfscanf(stdin, "%d %s", ap); va_end(ap);
Notes
- Whitespace in the format string matches any amount of whitespace in the input. - Input fields must match the expected format exactly or parsing will stop. - This implementation includes both direct DOS-level and POSIX-style fallback code paths, depending on compile-time `VFSCANF_DIRECT_DOS`.
Bugs
- Returns 0 on stream error instead of EOF (-1), which may not conform strictly to standard expectations. - Error and EOF handling uses AROS-specific flags and conventions. - `VFSCANF_DIRECT_DOS` path relies on AROS `UnGetC()` and `Flush()` calls, making portability limited.
vprintf()
Synopsis
int vprintf( const char * format, va_list args)
Function
Writes formatted output to the standard output stream using a variable argument list. This function is the `va_list`-based equivalent of `printf()`.
Inputs
format - A `printf`-style format string specifying how to format the output. args - A `va_list` containing the arguments to format and print.
Result
Returns the number of characters printed, or a negative value if an error occurs.
Example
va_list ap;
va_start(ap, fmt);
vprintf("%s: %d\n", ap);
va_end(ap);
Notes
- This function uses the AROS-specific global pointer `PosixCBase` to access `_stdout`, the standard output stream. - `vprintf()` is implemented by calling `vfprintf()` with `stdout`.
Bugs
- Assumes `PosixCBase` and `_stdout` are valid; if not, undefined behavior may occur. - Limited to the formatting capabilities of `vfprintf()`.
See also
vscanf()
Synopsis
int vscanf( const char * format, va_list args)
Function
Reads input from the standard input stream (`stdin`), interprets it according to the provided format string, and stores the results in the locations specified by the variable argument list.
Inputs
format - A `scanf`-style format string specifying how to interpret the input.
args - A `va_list` containing pointers to variables where the converted values
should be stored.
Result
Returns the number of input items successfully matched and assigned. Returns `EOF` if an input failure occurs before any conversion.
Example
va_list ap;
va_start(ap, fmt);
vscanf("%d %s", ap);
va_end(ap);
Notes
- This function is the `va_list` variant of `scanf()`. - Input is read from the standard input stream obtained from `PosixCBase->_stdin`. - The actual scanning is performed by `vfscanf()`.
Bugs
- Assumes `PosixCBase` and `_stdin` are properly initialized. - Behavior is undefined if arguments do not match the format string.
wait()
Synopsis
pid_t wait( int *status)
Function
Waits for child process to change state. State change is one of the
following events: child has exited, child was terminated by a signal,
child was stopped by a signal, child was resumed by a signal.
The function stores status of the process that changed state in the
pointer given as status argument.
The following macros can be used to extract information from the
status value:
WIFEXITED(status) - true if the process has exited
WEXITSTATUS(status) - exit status of the exited process
WIFSIGNALED(status) - true if the child process was terminated by a
signal
WTERMSIG(status) - number of the signal that caused process
termination
WIFSTOPPED(status) - true if the child process was stopped by a
signal
WSTOPSIG(status) - number of the signal that caused child process
stop
WIFCONTINUED(status) - true if the child process was resumed by the
SIGCONT signal.
Parent process will be suspended until a child changes state. If a
child process has already changed state, function returns immediately.
Inputs
status - Pointer to int where child return status will be stored or NULL if you don't want to store status.
Result
Process id of the child process on success or -1 on error. If an error occurred, the global variable errno is set.
Notes
This function will work only for child processes notifying parent process of their death, for example processes created by vfork() call. If you want to use it for other processes, remember to set the NP_NotifyOnDeath tag value to TRUE during child process creation.
See also
waitpid()
Synopsis
pid_t waitpid( pid_t pid, int *status, int options)
Function
Waits for child process with given process id to change state. State
change is one of the following events: child has exited, child was
terminated by a signal, child was stopped by a signal, child was
resumed by a signal.
The function stores status of the process that changed state in the
pointer given as status argument.
The following macros can be used to extract information from the
status value:
WIFEXITED(status) - true if the process has exited
WEXITSTATUS(status) - exit status of the exited process
WIFSIGNALED(status) - true if the child process was terminated by a
signal
WTERMSIG(status) - number of the signal that caused process
termination
WIFSTOPPED(status) - true if the child process was stopped by a
signal
WSTOPSIG(status) - number of the signal that caused child process
stop
WIFCONTINUED(status) - true if the child process was resumed by the
SIGCONT signal.
Unless WNOHANG option is set, parent process will be suspended until a
child changes state. If a child process has already changed state,
function returns immediately.
Inputs
pid - Process id of the process you want to wait for or -1 to wait for
any child process
status - Pointer to int where child status will be stored or NULL if
you don't want to store status.
options - ORed zero or more of the following constants:
WNOHANG - return immediately if no child process changed state
Result
Process id of the child process on success or -1 on error. If an error occurred, the global variable errno is set.
Notes
This function will work only for child processes notifying parent process of their death, for example processes created by vfork() call. If you want to use it for other processes, remember to set the NP_NotifyOnDeath tag value to TRUE during child process creation.
See also
wcscoll_l()
Synopsis
nt wcscoll_l( const wchar_t *ws1, const wchar_t *ws2, locale_t locale)
wcsnrtombs()
Synopsis
size_t wcsnrtombs( char * restrict dst, const wchar_t ** restrict src, size_t nwc, size_t len, mbstate_t * restrict ps ) FUNCTION Converts at most 'nwc' wide characters from the string pointed to by *src into a corresponding multibyte character string. The conversion uses the current locale (UTF-8 assumed here) and updates the src pointer to point past the last converted wide character.
Inputs
dst - Pointer to destination multibyte buffer (may be NULL).
src - Address of the wide character string pointer. The pointer is updated
during conversion. If dst is NULL, the function returns the number
of bytes that would result from the conversion.
nwc - Maximum number of wide characters to convert.
len - Maximum number of bytes to write.
ps - Conversion state object (ignored in this implementation).
Result
Returns the number of bytes written or needed. Returns (size_t)-1 on conversion error and sets errno to EILSEQ.
Notes
This implementation assumes stateless UTF-8 encoding and does not currently use mbstate_t. It wraps around wcrtomb().
wcswcs()
Synopsis
har_t * wcswcs( const wchar_t *haystack, const wchar_t *needle)
Function
Locates the first occurrence of the wide-character string 'needle' in the wide-character string 'haystack'. Returns a pointer to the start of the located substring, or NULL if not found.
Inputs
haystack -- wide-character string to be searched. needle -- wide-character string to search for.
Result
Pointer to the first occurrence of 'needle' in 'haystack', or NULL if no match is found.
Notes
If 'needle' is an empty string, 'haystack' is returned.
See also
wcswidth()
Synopsis
int wcswidth( const wchar_t *pwcs, size_t n)
Function
Sum the terminal-column estimates for a bounded sequence of wide characters.
Inputs
pwcs - Readable sequence ending at a null wide character
or containing at least n elements. May be NULL when
n is zero.
n - Maximum number of wchar_t elements to examine, not
a byte count or a column limit.
Result
The sum of wcwidth() results before the first null wide character or after n elements, whichever comes first. Returns -1 immediately if wcwidth() rejects an examined value; no partial sum is returned. Returns 0 when n is zero or the sequence starts with a null wide character.
Notes
Include <wchar.h>. The sequence is not modified and its pointer is not retained. The function does not change errno. Widths are added per element; no grapheme-cluster analysis or terminal-state tracking is performed. See wcwidth() for classification limits.
Bugs
The sum is accumulated in int without an overflow check. Keep the accumulated width at or below INT_MAX; exceeding it causes signed integer overflow rather than a reported error.
See also
wcsxfrm_l()
Synopsis
size_t wcsxfrm_l( wchar_t *dest, const wchar_t *src, size_t n, locale_t loc)
Function
Copy a wide-character string as a C-locale collation key.
Inputs
dest - Destination buffer with room for n wchar_t elements.
Use NULL with n equal to zero to measure the key.
Source and destination must not overlap.
src - Readable null-terminated wide-character string,
including when n is zero.
n - Destination capacity in wchar_t elements, not bytes.
loc - Ignored; no locale data is read.
Result
The length of src in wchar_t elements, excluding its null terminator. A return value less than n indicates a complete key if dest was supplied. A terminated prefix is not a complete key when the return value is at least n.
Notes
Include <wchar.h> with _POSIX_C_SOURCE set to at least 200809L. No storage is allocated and no pointer is retained. When dest is non-NULL and n is positive, the function copies at most n - 1 elements and appends a null wide character. The remaining buffer elements are unchanged. With n equal to zero or dest equal to NULL, it only measures src.
Bugs
Locale-specific collation is not implemented. The function uses wcsxfrm() and ignores loc.
See also
wcwidth()
Synopsis
int wcwidth( wchar_t wc)
Function
Estimate the number of terminal columns occupied by one wide character.
Inputs
wc - Character value to classify.
Result
0 for the null character or a value in the built-in zero-width table; -1 for C0 controls other than null and for values 0x7F through 0x9F. Negative values also return -1 when wchar_t is signed. Otherwise, returns 2 for the built-in wide ranges and 1 for all remaining values.
Notes
Include <wchar.h>. Classification uses fixed ranges identified in the source as Unicode 5.0 data. It does not consult the current locale, terminal or font. The function does not change errno.
Bugs
The result does not validate a Unicode scalar value or establish that a character is printable. Surrogate values and values above U+10FFFF are not rejected as such. The fixed ranges do not account for newer character assignments or terminal-specific rendering.
See also
write()
Synopsis
ssize_t write( int fd, const void * buf, size_t count)
Function
Write an amount of characters to the specified file descriptor.
Inputs
fd - The file descriptor to write to buf - Write these bytes into the file descriptor count - Write that many bytes
Result
The number of characters written or -1 on error.