======
posixc
======

.. This document is automatically generated. Don't edit it!

`Index <index>`_

----------

======================================= ======================================= ======================================= ======================================= 
`--background_POSIX--`_                 `__get_default_file()`_                 `__path_a2u()`_                         `__path_u2a()`_                         
`__posixc_assert()`_                    `__posixc_get_environptr()`_            `__progonly_execl()`_                   `__progonly_execlp()`_                  
`__progonly_execv()`_                   `__progonly_execve()`_                  `__progonly_execvp()`_                  `__progonly_set_environptr()`_          
`access()`_                             `alphasort()`_                          `alphasort64()`_                        `basename()`_                           
`chdir()`_                              `chmod()`_                              `chown()`_                              `clearerr()`_                           
`clock_gettime()`_                      `close()`_                              `closedir()`_                           `creat()`_                              
`creat64()`_                            `dirfd()`_                              `dirname()`_                            `dup()`_                                
`dup2()`_                               `endgrent()`_                           `endpwent()`_                           `fchdir()`_                             
`fchmod()`_                             `fchown()`_                             `fclose()`_                             `fcntl()`_                              
`fdopen()`_                             `feof()`_                               `ferror()`_                             `fflush()`_                             
`fgetc()`_                              `fgetpos()`_                            `fgetpos64()`_                          `fgets()`_                              
`fgetwc()`_                             `fgetws()`_                             `fileno()`_                             `flock()`_                              
`flockfile()`_                          `fopen()`_                              `fopen64()`_                            `fprintf()`_                            
`fputc()`_                              `fputs()`_                              `fputwc()`_                             `fread()`_                              
`freopen()`_                            `fscanf()`_                             `fseek()`_                              `fseeko()`_                             
`fseeko64()`_                           `fsetpos()`_                            `fsetpos64()`_                          `fstat()`_                              
`fstat64()`_                            `fsync()`_                              `ftell()`_                              `ftello()`_                             
`ftello64()`_                           `ftime()`_                              `ftruncate()`_                          `funlockfile()`_                        
`fwprintf()`_                           `fwrite()`_                             `gcvt()`_                               `getc()`_                               
`getc_unlocked()`_                      `getchar()`_                            `getcwd()`_                             `getegid()`_                            
`getenv()`_                             `geteuid()`_                            `getfsstat()`_                          `getgid()`_                             
`getgrent()`_                           `getgrgid()`_                           `getgrnam()`_                           `getgroups()`_                          
`getloadavg()`_                         `getlogin()`_                           `getopt()`_                             `getopt_long()`_                        
`getopt_long_only()`_                   `getpass()`_                            `getpgid()`_                            `getpgrp()`_                            
`getpid()`_                             `getppid()`_                            `getpwent()`_                           `getpwnam()`_                           
`getpwuid()`_                           `getrlimit()`_                          `gets()`_                               `gettimeofday()`_                       
`getuid()`_                             `getw()`_                               `ioctl()`_                              `isatty()`_                             
`jrand48()`_                            `kill()`_                               `lcong48()`_                            `link()`_                               
`lrand48()`_                            `lseek()`_                              `lseek64()`_                            `lstat()`_                              
`lstat64()`_                            `mbsnrtowcs()`_                         `mkdir()`_                              `mknod()`_                              
`mkstemp()`_                            `mktemp()`_                             `mrand48()`_                            `nanosleep()`_                          
`nrand48()`_                            `open()`_                               `opendir()`_                            `pclose()`_                             
`perror()`_                             `pipe()`_                               `popen()`_                              `posix_memalign()`_                     
`printf()`_                             `pselect()`_                            `putc()`_                               `putchar()`_                            
`putenv()`_                             `puts()`_                               `putw()`_                               `putwc()`_                              
`putwchar()`_                           `rand_r()`_                             `read()`_                               `readdir()`_                            
`readdir64()`_                          `realpath()`_                           `remove()`_                             `rename()`_                             
`rewind()`_                             `rewinddir()`_                          `rmdir()`_                              `scandir()`_                            
`scandir64()`_                          `scanf()`_                              `seed48()`_                             `seekdir()`_                            
`select()`_                             `setbuf()`_                             `setegid()`_                            `setenv()`_                             
`seteuid()`_                            `setgid()`_                             `setgrent()`_                           `setlinebuf()`_                         
`setpwent()`_                           `setrlimit()`_                          `setsid()`_                             `setuid()`_                             
`setvbuf()`_                            `sigaction()`_                          `sigaddset()`_                          `sigdelset()`_                          
`sigemptyset()`_                        `sigfillset()`_                         `sigismember()`_                        `siglongjmp()`_                         
`sigpending()`_                         `sigprocmask()`_                        `sigsuspend()`_                         `sleep()`_                              
`srand48()`_                            `stat()`_                               `stat64()`_                             `statfs()`_                             
`strerror()`_                           `strerror_r()`_                         `strftime_l()`_                         `swab()`_                               
`symlink()`_                            `sysconf()`_                            `system()`_                             `tcgetattr()`_                          
`tcgetpgrp()`_                          `tcsetattr()`_                          `telldir()`_                            `tempnam()`_                            
`times()`_                              `tmpfile()`_                            `tmpnam()`_                             `towlower_l()`_                         
`towupper_l()`_                         `truncate()`_                           `ttyname()`_                            `umask()`_                              
`uname()`_                              `ungetc()`_                             `unlink()`_                             `unsetenv()`_                           
`updatestdio()`_                        `usleep()`_                             `utime()`_                              `utimes()`_                             
`vfork()`_                              `vfprintf()`_                           `vfscanf()`_                            `vfwprintf()`_                          
`vprintf()`_                            `vscanf()`_                             `vwprintf()`_                           `wait()`_                               
`waitpid()`_                            `wcscoll()`_                            `wcscoll_l()`_                          `wcsnrtombs()`_                         
`wcstoimax()`_                          `wcstoll()`_                            `wcstoull()`_                           `wcstoumax()`_                          
`wcswcs()`_                             `wprintf()`_                            `write()`_                              
======================================= ======================================= ======================================= ======================================= 

-----------

--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.



See also
~~~~~~~~

`stdc.library/assert() <./stdc#assert>`_ `stdc.library/__assert() <./stdc#__assert>`_ 

----------

__posixc_get_environptr()
=========================

Synopsis
~~~~~~~~
::

  char ***__posixc_get_environptr(
     void)


Function
~~~~~~~~
::

     This function the get pointer to the child environ global variable
     currently used by posixc.library.


Inputs
~~~~~~
::

     -


Result
~~~~~~
::

     environptr - ptr to the child environ variable (== &environ).
                  NULL is return if envirion emulation is disabled.



See also
~~~~~~~~

`__progonly_set_environptr()`_ 

----------

__progonly_execl()
==================

Synopsis
~~~~~~~~
::

  int __progonly_execl(
     const char *path,
     const char *arg, va_list args)
     

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.



See also
~~~~~~~~

`execve()`_ `execlp()`_ `execv()`_ `execvp()`_   

----------

__progonly_execlp()
===================

Synopsis
~~~~~~~~
::

  int __progonly_execlp(
     const char *file,
     const char *arg, va_list args)
     

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.



See also
~~~~~~~~

`execve()`_ `execl()`_ `execv()`_ `execvp()`_   

----------

__progonly_execv()
==================

Synopsis
~~~~~~~~
::

  int __progonly_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.



See also
~~~~~~~~

`execve()`_ `execl()`_ `execlp()`_ `execvp()`_   

----------

__progonly_execve()
===================

Synopsis
~~~~~~~~
::

  int __progonly_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.



----------

__progonly_execvp()
===================

Synopsis
~~~~~~~~
::

  int __progonly_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.



See also
~~~~~~~~

`execve()`_ `execl()`_ `execlp()`_ `execv()`_   

----------

__progonly_set_environptr()
===========================

Synopsis
~~~~~~~~
::

  int __progonly_set_environptr(
     char ***environptr)


Function
~~~~~~~~
::

     This function is called to enable environ emulation mode.


Inputs
~~~~~~
::

     environptr - ptr to the child environ variable (== &environ).


Result
~~~~~~
::

     0 on fail, other value on success


Notes
~~~~~
::

     This function will enable environ emulation. This means that
     all current DOS local variables are converted to the 'var=value'
     format and be accessible through char **environ.


Bugs
~~~~
::

     At the moment only a static list is supported. getenv() and setenv()
     don't use this yet so changes done with these functions are not
     reflected in environ.
     This is still TODO.



See also
~~~~~~~~

`__posixc_get_environptr()`_ `getenv()`_ `setenv()`_ 

----------

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
~~~~~~~~

`open()`_ `ftruncate()`_ 

----------

alphasort()
===========

Synopsis
~~~~~~~~
::

  int alphasort(
     const struct dirent **a,
     const struct dirent **b
     )


Function
~~~~~~~~
::

     Support function for scandir().



See also
~~~~~~~~

`scandir()`_ 

----------

alphasort64()
=============

Synopsis
~~~~~~~~
::

  int alphasort64(
     const struct dirent64 **a,
     const struct dirent64 **b
     )


Function
~~~~~~~~
::

     Support function for scandir64().



See also
~~~~~~~~

`scandir()`_ 

----------

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
~~~~~~~~

`dirname()`_ 

----------

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
~~~~~~~~

`fchmod()`_ 

----------

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
~~~~~~~~

`ferror()`_ 

----------

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.



See also
~~~~~~~~

`open()`_ `read()`_ `write()`_ `fopen()`_ 

----------

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.



See also
~~~~~~~~

`close()`_ `opendir()`_ `readdir()`_ `rewinddir()`_ `seekdir()`_ `telldir()`_ 

----------

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
~~~~~~~~

`open()`_ `close()`_ `write()`_ `fopen()`_ 

----------

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.



See also
~~~~~~~~

`open()`_ `close()`_ `write()`_ `fopen()`_ 

----------

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
~~~~~~~~

`open()`_ `readdir()`_ `closedir()`_ `rewinddir()`_ `seekdir()`_ `telldir()`_ 

----------

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
~~~~~~~~

`basename()`_ 

----------

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.



See also
~~~~~~~~

`bsdsocket.library/accept() <./bsdsocket#accept>`_ `open()`_ `close()`_ `fcntl()`_ `pipe()`_ `bsdsocket.library/socket() <./bsdsocket#socket>`_ 

----------

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.



See also
~~~~~~~~

`bsdsocket.library/accept() <./bsdsocket#accept>`_ `open()`_ `close()`_ `fcntl()`_ `pipe()`_ `bsdsocket.library/socket() <./bsdsocket#socket>`_ 

----------

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
~~~~~~~~

`usergroup.library/endgrent() <./usergroup#endgrent>`_ 

----------

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
~~~~~~~~

`usergroup.library/endpwent() <./usergroup#endpwent>`_ 

----------

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
~~~~~~~~

`chmod()`_ 

----------

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.



See also
~~~~~~~~

`fopen()`_ `open()`_ `close()`_ 

----------

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
~~~~~~~~

`open()`_ 

----------

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 com­patible
               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
~~~~~~~~

`open()`_ `fclose()`_ `fileno()`_ 

----------

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()`_ `clearerr()`_ 

----------

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
~~~~~~~~

`clearerr()`_ 

----------

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
~~~~~~~~

`getc()`_ `fputc()`_ `putc()`_ 

----------

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
~~~~~~~~

`fsetpos()`_ 

----------

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
~~~~~~~~

`fsetpos()`_ 

----------

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
     }



See also
~~~~~~~~

`fopen()`_ `fputs()`_ 

----------

fgetwc()
========

Synopsis
~~~~~~~~
::

  t_t fgetwc(
     FILE *stream)


Function
~~~~~~~~
::

     Read one wide character from the stream. If there is no character
     available or an error occurred, the function returns WEOF.


Inputs
~~~~~~
::

     stream - Read from this stream


Result
~~~~~~
::

     The wide character read or WEOF on end of file or error.



----------

fgetws()
========

Synopsis
~~~~~~~~
::

  ar_t *fgetws(
     wchar_t * restrict s, 
     int n, 
     FILE * restrict stream)


Function
~~~~~~~~
::

     Read one line of wide characters from the stream into the buffer.
     Reading will stop, when a newline ('\n') is encountered, WEOF
     or when the buffer is full. If a newline is read, then it is
     put into the buffer. The last wide character in the buffer is always
     '\0' (Therefore at most size-1 characters can be read in one go).


Inputs
~~~~~~
::

     s - Write wide characters into this buffer
     n - This is the size of the buffer in wide characters.
     stream - Read from this stream


Result
~~~~~~
::

     buffer or NULL in case of an error or EOF.


Example
~~~~~~~
::

     // Read a file line by line
     wchar_t line[256];

     // Read until WEOF
     while (fgetws (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
~~~~~~~~

`open()`_ 

----------

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.



----------

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.



See also
~~~~~~~~

`fclose()`_ `fread()`_ `fwrite()`_ `open()`_ `fgets()`_ `fgetc()`_ `fputs()`_ `fputc()`_ `getc()`_ `putc()`_ 

----------

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
~~~~~~~~

`fseeko64()`_ `ftello64()`_ 

----------

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.



See also
~~~~~~~~

`puts()`_ `fputc()`_ `putc()`_ 

----------

fputwc()
========

Synopsis
~~~~~~~~
::

  t_t fputwc(
     wchar_t wc, 
     FILE * fp) 


Function
~~~~~~~~
::

     Writes the wide character wc to the stream and advances the position indicator.


Inputs
~~~~~~
::

     wc - The wide character to write.
     fp - Pointer to a FILE object that identifies an output stream.
     

Result
~~~~~~
::

     On success, the character written is returned.



----------

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.



See also
~~~~~~~~

`fopen()`_ `fwrite()`_ 

----------

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 com­patible
              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.



See also
~~~~~~~~

`open()`_ `fclose()`_ `fileno()`_ 

----------

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
~~~~~~~~

`scanf()`_ 

----------

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.



See also
~~~~~~~~

`fopen()`_ `fwrite()`_ 

----------

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
~~~~~~~~

`fseek()`_ 

----------

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
~~~~~~~~

`fopen64()`_ `ftello64()`_ 

----------

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
~~~~~~~~

`fgetpos()`_ 

----------

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
~~~~~~~~

`fgetpos()`_ 

----------

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
~~~~~~~~

`stat()`_ 

----------

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
~~~~~~~~

`stat()`_ 

----------

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.



See also
~~~~~~~~

`fopen()`_ `fseek()`_ `fwrite()`_ 

----------

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
~~~~~~~~

`fopen64()`_ `ftello64()`_ 

----------

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
~~~~~~~~

`gettimeofday()`_ 

----------

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
~~~~~~~~

`open()`_ `truncate()`_ 

----------

funlockfile()
=============

Synopsis
~~~~~~~~
::

  void funlockfile(
     FILE *file)


Function
~~~~~~~~
::

     Relinquish exclusive access to the file.



----------

fwprintf()
==========

Synopsis
~~~~~~~~
::

  int fwprintf(
     FILE * restrict fh,
     const wchar_t * restrict format,
     ...)


Function
~~~~~~~~
::

     Format a wide 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.



----------

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
~~~~~~~~

`fopen()`_ 

----------

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
~~~~~~~~

`stdc.library/sprintf() <./stdc#sprintf>`_ 

----------

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
~~~~~~~~

`fgetc()`_ `fputc()`_ `putc()`_ 

----------

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
~~~~~~~~

`getc()`_ `fputc()`_ `putc()`_ 

----------

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.



See also
~~~~~~~~

`fgetc()`_ `getc()`_ `fputc()`_ `putc()`_ 

----------

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
~~~~~~~~

`chdir()`_ 

----------

getegid()
=========

Synopsis
~~~~~~~~
::

  gid_t getegid(
     void)


Function
~~~~~~~~
::

     Returns the effective group ID of the calling process



See also
~~~~~~~~

`setgid()`_   

----------

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.



----------

geteuid()
=========

Synopsis
~~~~~~~~
::

  uid_t geteuid(
     void)



See also
~~~~~~~~

`getuid()`_   

----------

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
~~~~~~~~

`setgid()`_   

----------

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
~~~~~~~~

`usergroup.library/endgrent() <./usergroup#endgrent>`_ 

----------

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
~~~~~~~~

`usergroup.library/getgrgid() <./usergroup#getgrgid>`_ 

----------

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
~~~~~~~~

`usergroup.library/getgrnam() <./usergroup#getgrnam>`_ 

----------

getgroups()
===========

Synopsis
~~~~~~~~
::

  int getgroups(
     int gidsetlen,
     gid_t *gidset)


Notes
~~~~~
::

     Not implemented.



----------

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()`_ 

----------

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()`_ 

----------

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
~~~~~~~~

`getopt()`_ `getopt_long()`_ 

----------

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
~~~~~~~~

`usergroup.library/getpwent() <./usergroup#getpwent>`_ 

----------

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
~~~~~~~~

`usergroup.library/getpwnam() <./usergroup#getpwnam>`_ 

----------

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
~~~~~~~~

`usergroup.library/getpwuid() <./usergroup#getpwuid>`_ 

----------

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
~~~~~~~~

`setrlimit()`_ 

----------

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
~~~~~~~~

`fgets()`_ 

----------

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.



See also
~~~~~~~~

`stdc.library/ctime() <./stdc#ctime>`_ `stdc.library/asctime() <./stdc#asctime>`_ `stdc.library/localtime() <./stdc#localtime>`_ `stdc.library/time() <./stdc#time>`_ 

----------

getuid()
========

Synopsis
~~~~~~~~
::

  uid_t getuid(
     void)


Function
~~~~~~~~
::

     Returns the real user ID of the calling process.



See also
~~~~~~~~

`geteuid()`_   

----------

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
~~~~~~~~

`fread()`_ 

----------

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
~~~~~~
::

     EBADF   - fd is not valid
     EFAULT  - no valid argument
     ENOTTY  - fd is not of required type


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
~~~~~
::

     Width and height are the width and height of the intuition window.


Bugs
~~~~
::

     Only the requests listed above are implemented.



----------

isatty()
========

Synopsis
~~~~~~~~
::

  int isatty(
     int fd)
     


----------

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.



----------

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
~~~~~~~~

`fopen()`_ `fwrite()`_ 

----------

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
~~~~~~~~

`fopen()`_ `fwrite()`_ 

----------

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
~~~~~~~~

`stat()`_ `fstat()`_ 

----------

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.



See also
~~~~~~~~

`stat64()`_ `fstat64()`_ 

----------

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().



See also
~~~~~~~~

`wcsnrtombs()`_ `stdc.library/mbrtowc() <./stdc#mbrtowc>`_ `stdc.library/mbstowcs() <./stdc#mbstowcs>`_ `stdc.library/wcsrtombs() <./stdc#wcsrtombs>`_ 

----------

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
~~~~~~~~

`chmod()`_ `stat()`_ `umask()`_ 

----------

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.



----------

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
~~~~~~~~

`close()`_ `read()`_ `write()`_ `fopen()`_ 

----------

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



See also
~~~~~~~~

`open()`_ `readdir()`_ `closedir()`_ `rewinddir()`_ `seekdir()`_ `telldir()`_ 

----------

pclose()
========

Synopsis
~~~~~~~~
::

  int pclose(
     FILE * stream)


Notes
~~~~~
::

     Not implemented.



See also
~~~~~~~~

`popen()`_ 

----------

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.



See also
~~~~~~~~

`fclose()`_ `fread()`_ `fwrite()`_ `pipe()`_ `pclose()`_ 

----------

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.



See also
~~~~~~~~

`stdc.library/aligned_alloc() <./stdc#aligned_alloc>`_ `stdc.library/calloc() <./stdc#calloc>`_ `stdc.library/free() <./stdc#free>`_ `stdc.library/malloc() <./stdc#malloc>`_ 

----------

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.



See also
~~~~~~~~

`fprintf()`_ `vprintf()`_ `vfprintf()`_ `stdc.library/sprintf() <./stdc#sprintf>`_ `stdc.library/vsprintf() <./stdc#vsprintf>`_ `stdc.library/vsnprintf() <./stdc#vsnprintf>`_ 

----------

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
~~~~~~~~

`fputc()`_ 

----------

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);



See also
~~~~~~~~

`fputs()`_ `printf()`_ `fprintf()`_ `putc()`_ `fputc()`_ 

----------

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
~~~~~~~~

`fwrite()`_ 

----------

putwc()
=======

Synopsis
~~~~~~~~
::

  wint_t putwc(
     wchar_t wc,
     FILE * fp)


Function
~~~~~~~~
::

     Writes the wide character wc to the stream and advances the position indicator.


Inputs
~~~~~~
::

     wc - The wide character to write.
     fp - Pointer to a FILE object that identifies an output stream.
     

Result
~~~~~~
::

     On success, the character written is returned.



----------

putwchar()
==========

Synopsis
~~~~~~~~
::

  t_t putwchar(
     wchar_t wc)


Function
~~~~~~~~
::

     Writes the wide character wc to the stream and advances the position indicator.


Inputs
~~~~~~
::

     wc - The wide character to write.
     

Result
~~~~~~
::

     On success, the character written is returned.



----------

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.



See also
~~~~~~~~

`rand()`_ `srand()`_ `drand48()`_ `random()`_ `arc4random()`_ 

----------

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.



See also
~~~~~~~~

`open()`_ `read()`_ `fread()`_ 

----------

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
~~~~~~~~

`read()`_ `opendir()`_ `closedir()`_ `rewinddir()`_ `seekdir()`_ `telldir()`_ 

----------

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
~~~~~~~~

`read()`_ `opendir()`_ `closedir()`_ `rewinddir()`_ `seekdir()`_ `telldir()`_ 

----------

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
~~~~~~~~

`getcwd()`_ `readlink()`_ `chdir()`_ 

----------

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
~~~~~~~~

`unlink()`_ 

----------

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.



See also
~~~~~~~~

stdio.h rename() `unlink()`_ `mkdir()`_ 

----------

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
~~~~~~~~

`fopen()`_ `fwrite()`_ `fseek()`_ `clearerr()`_ 

----------

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.
     


See also
~~~~~~~~

`unlink()`_ `remove()`_ 

----------

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
~~~~~~~~

`alphasort()`_ 

----------

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
~~~~~~~~

`alphasort()`_ 

----------

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.



See also
~~~~~~~~

`fscanf()`_ `vscanf()`_ `vfscanf()`_ `stdc.library/sscanf() <./stdc#sscanf>`_ `stdc.library/vsscanf() <./stdc#vsscanf>`_ 

----------

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.



See also
~~~~~~~~

`setvbuf()`_ `fflush()`_ `fread()`_ `fwrite()`_ 

----------

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
~~~~~~~~

`usergroup.library/setgrent() <./usergroup#setgrent>`_ 

----------

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
~~~~~~~~

`setvbuf()`_ 

----------

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
~~~~~~~~

`usergroup.library/setpwent() <./usergroup#setpwent>`_ 

----------

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
~~~~~~~~

`getrlimit()`_ 

----------

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.



See also
~~~~~~~~

`fopen()`_ `fflush()`_ `fclose()`_ `perror()`_ 

----------

sigaction()
===========

Synopsis
~~~~~~~~
::

  int sigaction(
     int signum,
     const  struct  sigaction  *act,
     struct sigaction *oldact)


Notes
~~~~~
::

     Not implemented.



----------

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)


Notes
~~~~~
::

     Not implemented.



----------

sigprocmask()
=============

Synopsis
~~~~~~~~
::

  int sigprocmask(
     int  how,
     const  sigset_t *set,
     sigset_t *oldset)


Function
~~~~~~~~
::

     Allow the caller to examine or change (or both) the
     signal mask of the calling thread.


Notes
~~~~~
::

     Not implemented.



----------

sigsuspend()
============

Synopsis
~~~~~~~~
::

  int sigsuspend(
     const sigset_t *mask)


Function
~~~~~~~~
::

     replace the callers signal mask, and suspend it
     until it signaled to terminate, or to invoke a
     signal handler.

     If the signal terminates the process, sigsuspend()
     doesn't return.

     If the signal is caught, sigsuspend() returns following the
     signal handler, and the signal mask is restored to
     the state prior to calling sigsuspend().

     SIGKILL or SIGSTOP cannot be blocked; specifying
     them in the mask has no effect on the process's signal mask.


Result
~~~~~~
::

     always returns -1, normally with the error EINTR.


Notes
~~~~~
::

     Not implemented.

     Normally used in conjunction with sigprocmask(), to prevent
     signal delivery during critical code sections. Callers must
     block the signals with sigprocmask(). On completion, the caller
     waits for signals by calling sigsuspend() with the return value
     of sigprocmask()



See also
~~~~~~~~

`kill()`_ `pause()`_ `sigaction()`_ stdc/signal() `sigprocmask()`_ `sigwaitinfo()`_ `sigsetops()`_ `sigwait()`_ 

----------

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
~~~~~~~~

`lstat()`_ `fstat()`_ 

----------

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.



See also
~~~~~~~~

`lstat64()`_ `fstat64()`_ 

----------

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



----------

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.



See also
~~~~~~~~

`stdc.library/strerror() <./stdc#strerror>`_ `stdc.library/strerror() <./stdc#strerror>`_ 

----------

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
~~~~~~~~

`strerror()`_ `__stdc_strerror()`_ 

----------

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
~~~~~~~~

`strftime()`_ 

----------

swab()
======

Synopsis
~~~~~~~~
::

  void swab(
     const void *from,
     void *to,
     size_t len)



----------

symlink()
=========

Synopsis
~~~~~~~~
::

  int symlink(
     const char *oldpath,
     const char *newpath)



----------

sysconf()
=========

Synopsis
~~~~~~~~
::

  long sysconf(
     int name)


Notes
~~~~~
::

     Currently only _SC_ARG_MAX handling is implemented



----------

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`.



See also
~~~~~~~~

`exec()`_ `popen()`_ `fork()`_ `execl()`_ `waitpid()`_ 

----------

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
~~~~~~~~

`ioctl()`_ 

----------

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
~~~~~
::

     Will return success, if *any* of the changes were successful.
     Currently supports only ICANON flag



See also
~~~~~~~~

`ioctl()`_ 

----------

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.




See also
~~~~~~~~

`fopen()`_ `mkstemp()`_ 

----------

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.



See also
~~~~~~~~

`tmpfile()`_ `mkstemp()`_ `mktemp()`_ 

----------

towlower_l()
============

Synopsis
~~~~~~~~
::

  wint_t towlower_l(
     wint_t wc,
     locale_t locale)



See also
~~~~~~~~

`towupper()`_ `towctrans()`_ 

----------

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
~~~~~~~~

`towlower()`_ `towctrans()`_ 

----------

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
~~~~~~~~

`open()`_ 

----------

ttyname()
=========

Synopsis
~~~~~~~~
::

  char * ttyname(
     int fd)
     

Notes
~~~~~
::

     Not implemented.



----------

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.



See also
~~~~~~~~

`fgetc()`_ `getc()`_ `fputc()`_ `putc()`_ 

----------

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
~~~~~~~~

`remove()`_ 

----------

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.



----------

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
~~~~~~~~

`nanosleep()`_ 

----------

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()`_ 

----------

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
~~~~~~~~

`utime()`_ 

----------

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.



See also
~~~~~~~~

`execl()`_ `execve()`_ `execlp()`_ `execv()`_ `execvp()`_ 

----------

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.



See also
~~~~~~~~

`fprintf()`_ `printf()`_ `vprintf()`_ `stdc.library/vsprintf() <./stdc#vsprintf>`_ `stdc.library/vsnprintf() <./stdc#vsnprintf>`_ `va_start()`_ `va_list`_ 

----------

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.



See also
~~~~~~~~

`scanf()`_ `fscanf()`_ `vscanf()`_ `stdc.library/sscanf() <./stdc#sscanf>`_ `stdc.library/vsscanf() <./stdc#vsscanf>`_ `va_start()`_ `va_list`_ 

----------

vfwprintf()
===========

Synopsis
~~~~~~~~
::

  int vfwprintf(
     FILE  * restrict stream,
     const wchar_t * restrict format,
     va_list args)


Function
~~~~~~~~
::

     Format a list of arguments and print them on the specified stream.


Inputs
~~~~~~
::

     stream - A stream on which one can write
     format - A wprintf() format string.
     args - A list of arguments for the format string.


Result
~~~~~~
::

     The number of characters written.



----------

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
~~~~~~~~

`printf()`_ `fprintf()`_ `vfprintf()`_ `vsprintf()`_ `puts()`_ `fputs()`_ 

----------

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.



See also
~~~~~~~~

`scanf()`_ `fscanf()`_ `vfscanf()`_ `gets()`_ `fgets()`_ 

----------

vwprintf()
==========

Synopsis
~~~~~~~~
::

  int vwprintf(
     const wchar_t * restrict format,
     va_list args)


Function
~~~~~~~~
::

     Format a list of arguments and print them on the standard output.


Inputs
~~~~~~
::

     format - A wprintf() format string.
     args - A list of arguments for the format string.


Result
~~~~~~
::

     The number of characters written.



----------

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()`_ 

----------

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
~~~~~~~~

`wait()`_ 

----------

wcscoll()
=========

Synopsis
~~~~~~~~
::

  nt wcscoll(
   const wchar_t *ws1, const wchar_t *ws2)


Function
~~~~~~~~
::

     Compares the two wide-character strings 'ws1' and 'ws2' according
     to the current locale's collation order.


Inputs
~~~~~~
::

     ws1 -- first wide-character string
     ws2 -- second wide-character string


Result
~~~~~~
::

     Returns < 0 if ws1 < ws2, 0 if ws1 == ws2, > 0 if ws1 > ws2.


Notes
~~~~~
::

     This implementation ignores locale collation and performs a
     binary comparison using wcscmp().



See also
~~~~~~~~

`wcscmp()`_ `wcsxfrm()`_ `strcoll()`_ 

----------

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().



See also
~~~~~~~~

`stdc.library/wcrtomb() <./stdc#wcrtomb>`_ `stdc.library/wcsrtombs() <./stdc#wcsrtombs>`_ `stdc.library/wcstombs() <./stdc#wcstombs>`_ `stdc.library/mbsrtowcs() <./stdc#mbsrtowcs>`_ 

----------

wcstoimax()
===========

Synopsis
~~~~~~~~
::

  intmax_t wcstoimax(
     const wchar_t * restrict nptr,
     wchar_t       ** restrict endptr,
     int                     base)


Function
~~~~~~~~
::

     Converts a wide-character string of digits into an integer of type
     intmax_t, according to the specified base. This function behaves like
     wcstol() but returns an intmax_t result.


Inputs
~~~~~~
::

     nptr    - Pointer to the wide-character string to convert.
     endptr  - If non-NULL, stores the address of the first character
               after the number.
     base    - The base for conversion (e.g., 10 for decimal, 16 for hex).


Result
~~~~~~
::

     Returns the converted value as an intmax_t. If no valid conversion could
     be performed, returns 0 and stores nptr in *endptr (if endptr is non-NULL).


Example
~~~~~~~
::

     wchar_t *str = L"12345";
     wchar_t *end;
     intmax_t value = wcstoimax(str, &end, 10);


Notes
~~~~~
::

     Does not set errno on overflow or underflow, contrary to the C99 standard.
     Behavior is otherwise compatible with the standard library definition.


Bugs
~~~~
::

     errno is not set on conversion errors or range overflows.



See also
~~~~~~~~

`wcstol()`_ `wcstoll()`_ `strtoimax()`_ `strtol()`_ 

----------

wcstoll()
=========

Synopsis
~~~~~~~~
::

  g long wcstoll(
 const wchar_t *nptr,
 wchar_t **endptr,
 int base)


Function
~~~~~~~~
::

     Converts the initial part of wide string nptr to a long long integer,
     respecting the base (2 to 36) or auto-detect if base is 0.


Inputs
~~~~~~
::

     nptr   - Wide string input.
     endptr - If not NULL, updated to point after last converted character.
     base   - Numeric base for conversion.


Result
~~~~~~
::

     Returns converted long long integer. On overflow, returns LLONG_MAX or
     LLONG_MIN and sets errno to ERANGE. Returns 0 if no conversion.


Example
~~~~~~~
::


     wchar_t *end;
     long long val = wcstoll(L"123456789LLxyz", &end, 10);
     // val == 123456789LL, *end == L'x'


Notes
~~~~~
::

     Handles optional whitespace and sign. Base 0 auto-detects hex/octal/decimal.



See also
~~~~~~~~

`wcstol()`_ `wcstoul()`_ `wcstoull()`_ 

----------

wcstoull()
==========

Synopsis
~~~~~~~~
::

  igned long long wcstoull(
 const wchar_t *nptr,
 wchar_t **endptr,
 int base)


Function
~~~~~~~~
::

     Converts the initial part of wide string nptr to an unsigned long long
     integer according to the specified base or auto-detect if base is 0.


Inputs
~~~~~~
::

     nptr   - Wide string input.
     endptr - If not NULL, set to the character after last consumed character.
     base   - Numeric base for conversion (0 or 2 to 36).


Result
~~~~~~
::

     Returns converted unsigned long long integer. On overflow, returns
     ULLONG_MAX and sets errno to ERANGE. Returns 0 if no conversion.


Example
~~~~~~~
::


     wchar_t *end;
     unsigned long long val = wcstoull(L"18446744073709551615xyz", &end, 10);
     // val == 18446744073709551615ULL, *end == L'x'


Notes
~~~~~
::

     Supports optional whitespace and plus sign. Base 0 auto-detects.



See also
~~~~~~~~

`wcstol()`_ `wcstoll()`_ `wcstoul()`_ 

----------

wcstoumax()
===========

Synopsis
~~~~~~~~
::

  uintmax_t wcstoumax(
     const wchar_t *nptr,
     wchar_t       **endptr,
     int            base)


Function
~~~~~~~~
::

     Converts a wide-character string of digits into an unsigned integer
     according to the given base. This function is similar to wcstoul(),
     but returns a value of type uintmax_t.


Inputs
~~~~~~
::

     nptr    - Pointer to the wide-character string to be converted.
     endptr  - If non-NULL, the address of the first character after the
               number is stored here.
     base    - The numeric base for the conversion (e.g., 10 for decimal,
               16 for hexadecimal).


Result
~~~~~~
::

     The converted numeric value as a uintmax_t. If no valid digits are found,
     0 is returned, and if endptr is non-NULL, it is set to nptr.


Example
~~~~~~~
::

     wchar_t *str = L"FF";
     wchar_t *end;
     uintmax_t value = wcstoumax(str, &end, 16);


Notes
~~~~~
::

     The function does not set errno on overflow or underflow, contrary to
     the requirements of the C99 standard.


Bugs
~~~~
::

     errno is not set on range errors as required by the C99 standard.



See also
~~~~~~~~

`wcstoul()`_ `wcstoull()`_ `strtoumax()`_ `strtoul()`_ 

----------

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
~~~~~~~~

`wcsstr()`_ `wcschr()`_ `wcsrchr()`_ 

----------

wprintf()
=========

Synopsis
~~~~~~~~
::

  int wprintf(
     const wchar_t * restrict 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:

     \begin{itemize}
     \item Zero or more of the following flags:

     \begin{description}
     \item{#} specifying that the value should be converted to an
     ``alternate form''. For 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, 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.

     \item{0} specifying zero padding. For all conversions except n, the
     converted value is padded on the left with zeros rather than
     blanks. If a precision is given with a numeric conversion (d, i, o,
     u, i, x, and X), the 0 flag is ignored.

     \item{-} (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.

     \item{ } (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.

     \item{'} 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.

     \end{description}

     \item 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.

     \item 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.

     \item 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.

     \item 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.

     \item 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.

     \item 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.

     \item A Z character specifying that the following integer (d, i, o,
     u, i, x, and X), conversion corresponds to a size_t argument.

     \item 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:

     \begin{description}
     \item{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.

     \item{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.

     \item{f} 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.

     \item{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.

     \item{c} The int argument is converted to an unsigned char, and the
     resulting character is written.

     \item{s} The ``wchar_t *'' argument is expected to be a pointer to an
     array of wide character type (pointer to a wide 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.

     \item{p} The ``void *'' pointer argument is printed in hexadecimal
     (as if by %#x or %#lx).

     \item{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.

     \item{%} A `%' is written. No argument is converted. The complete
     conversion specification is `%%'.

     \end{description}
     \end{itemize}

     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 wide 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 <math.h>
      #include <stdio.h>
      #include <wchar.h>

      wchar_t *weekday, *month; // pointers to wide strings
      int day, hour, min;
      fwprintf(stdout, L"%ls, %ls %d, %.2d:%.2d\n",
              weekday, month, day, hour, min);
      fwprintf(stdout, L"pi = %.5f\n", 4 * atan(1.0));


Bugs
~~~~
::

     All functions are fully ANSI C3.159-1989 conformant, but provide
     the additional flags q, Z and ' as well as an additional behavior
     of the L and l flags. The latter may be considered to be a bug, as
     it changes the behavior 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 behavior
     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 swprintf and vswprintf assume an infinitely long string,
     callers must be careful not to overflow the actual space; this is
     often impossible to assure.



See also
~~~~~~~~

`fwprintf()`_ `vwprintf()`_ `vfwprintf()`_ `swprintf()`_ `vswprintf()`_ 

----------

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.



