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

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.

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.

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.

Synopsis

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

Function

Support function for scandir().

See also

__posixc_scandir()

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.library/__stdc_assert() stdc.library/__stdcio_assert()

Synopsis

int __posixc_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() __posixc_fopen()

Synopsis

int __posixc_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

__posixc_fopen() open() close()

Synopsis

int __posixc_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

__posixc_ferror() clearerr()

Synopsis

int __posixc_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()

Synopsis

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

Synopsis

int __posixc_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

__posixc_fsetpos()

Synopsis

 char * __posixc_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

__posixc_fopen() __posixc_fputs()

Synopsis

FILE * __posixc_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

__posixc_fclose() __posixc_fread() __posixc_fwrite() open() __posixc_fgets() fgetc() __posixc_fputs() __posixc_fputc() getc() putc()

Synopsis

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

Synopsis

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

Synopsis

int __posixc_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

__posixc_puts() __posixc_fputc() putc()

Synopsis

size_t __posixc_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

__posixc_fopen() __posixc_fwrite()

Synopsis

FILE *__posixc_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() __posixc_fclose() fileno()

Synopsis

int __posixc_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

__posixc_scanf()

Synopsis

int __posixc_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

__posixc_fopen() __posixc_fwrite()

Synopsis

int __posixc_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

__posixc_fseek()

Synopsis

int __posixc_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

__posixc_fgetpos()

Synopsis

int __posixc_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

__posixc_stat()

Synopsis

long __posixc_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

__posixc_fopen() __posixc_fseek() __posixc_fwrite()

Synopsis

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

Synopsis

size_t __posixc_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

__posixc_fopen()

Synopsis

int __posixc_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

`__posixc_fgetc()`_ getc() __posixc_fputc() putc()

Synopsis

char *__posixc_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.

Synopsis

char * __posixc_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

__posixc_fgets()

Synopsis

off_t __posixc_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

__posixc_fopen() __posixc_fwrite()

Synopsis

int __posixc_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

__posixc_stat() __posixc_fstat()

Synopsis

int __posixc_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

__posixc_fprintf() __posixc_vprintf() __posixc_vfprintf() stdc.library/sprintf() stdc.library/vsprintf() stdc.library/vsnprintf()

Synopsis

int __posixc_putchar(
   int c)

Synopsis

int __posixc_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

__posixc_fputs() __posixc_printf() __posixc_fprintf() putc() __posixc_fputc()

Synopsis

struct dirent *__posixc_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()

Synopsis

void __posixc_rewind(
   FILE * stream)

Function

Change the current position in a stream to the beginning.

Inputs

stream - Modify this stream

See also

__posixc_fopen() __posixc_fwrite() __posixc_fseek()

Synopsis

int __posixc_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

__posixc_alphasort()

Synopsis

int __posixc_scanf(
   const char * format,
   ...)

Result

The number of converted parameters

See also

__posixc_fscanf() __posixc_vscanf() __posixc_vfscanf() stdc.library/sscanf() stdc.library/vsscanf()

Synopsis

void __posixc_setbuf(
   FILE *stream,
   char *buf)

Notes

This is a simpler alias for setvbuf() according to manpage.

Synopsis

int __posixc_setvbuf(
   FILE *stream,
   char *buf,
   int mode,
   size_t size)

Synopsis

int __posixc_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

__posixc_lstat() __posixc_fstat()

Synopsis

char * __posixc_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.
It is aliased as strerror() in libposixc.a

See also

stdc.library/__stdc_strerror() stdc.library/strerror()

Synopsis

int __posixc_system(
   const char *string)

Function

Execute a command string. If string is NULL then 1 will be returned.

Inputs

string - command to execute or NULL

Result

Return value of command executed. If value < 0 errno indicates error.
1 is return if string is NULL.

Notes

The system() version of posixc.library will translate UNIX<>Amiga
if applicable as well as use a shell for executing text batch
commands.

Synopsis

FILE * __posixc_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

__posixc_fopen() mkstemp()

Synopsis

char *__posixc_tmpnam(
   char *s)

Synopsis

int __posixc_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() __posixc_fputc() putc()

Synopsis

int __posixc_vfprintf(
   FILE       * stream,
   const char * 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 printf() format string.
args - A list of arguments for the format string.

Result

The number of characters written.

Synopsis

int __posixc_vfscanf(
   FILE       * stream,
   const char * format,
   va_list      args)

Function

Read the scream, scan it as the format specified and write the
result of the conversion into the specified arguments.

Inputs

stream - A stream to read from
format - A scanf() format string.
args - A list of arguments for the results.

Result

The number of converted arguments.

Synopsis

int __posixc_vprintf(
   const char * format,
   va_list      args)

Function

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

Inputs

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

Result

The number of characters written.

Synopsis

int __posixc_vscanf(
   const char * format,
   va_list      args)

Function

Scan the standard input and convert it into the arguments as
specified by format.

Inputs

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

Result

The number of converted parameters.

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

Synopsis

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

Function

Support function for scandir64().

See also

__posixc_scandir()

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

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

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

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.

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

__posixc_ferror()

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.

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

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() __posixc_readdir() rewinddir() seekdir() telldir()

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

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() __posixc_readdir() closedir() rewinddir() seekdir() telldir()

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

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() open() close() fcntl() pipe() bsdsocket.library/socket()

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() open() close() fcntl() pipe() bsdsocket.library/socket()

Synopsis

void endgrent(
   void)

Notes

Not implemented.

Synopsis

void endpwent(
   void)

Notes

Not implemented.

Synopsis

int execl(
   const char *path,
   const char *arg, ...)

Function

Executes a file located in given path with specified arguments.

Inputs

path - Pathname of the file to execute.
arg - First argument passed to the executed file.
... - Other arguments passed to the executed file.

Result

Returns -1 and sets errno appropriately in case of error, otherwise
doesn't return.

See also

execve() execlp() execv() execvp()

Synopsis

int execlp(
   const char *file,
   const char *arg, ...)

Function

Executes a file with given name. The search paths for the executed
file are paths specified in the PATH environment variable.

Inputs

file - Name of the file to execute.
arg - First argument passed to the executed file.
... - Other arguments passed to the executed file.

Result

Returns -1 and sets errno appropriately in case of error, otherwise
doesn't return.

See also

execve() execl() execv() execvp()

Synopsis

int execv(
   const char *path,
   char *const argv[])

Function

Executes a file located in given path with specified arguments.

Inputs

path - Pathname of the file to execute.
argv - Array of arguments given to main() function of the executed
file.

Result

Returns -1 and sets errno appropriately in case of error, otherwise
doesn't return.

See also

execve() execl() execlp() execvp()

Synopsis

int execve(
   const char *filename,
   char *const argv[],
   char *const envp[])

Function

Executes a file with given name.

Inputs

filename - Name of the file to execute.
argv - Array of arguments provided to main() function of the executed
file.
envp - Array of environment variables passed as environment to the
executed program.

Result

Returns -1 and sets errno appropriately in case of error, otherwise
doesn't return.

Synopsis

int execvp(
   const char *file,
   char *const argv[])

Function

Executes a file with given name. The search paths for the executed
file are paths specified in the PATH environment variable.

Inputs

file - Name of the file to execute.
argv - Array of arguments given to main() function of the executed
file.

Result

Returns -1 and sets errno appropriately in case of error, otherwise
doesn't return.

See also

execve() execl() execlp() execv()

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.

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

Synopsis

int fchown(
   int fd,
   uid_t owner,
   gid_t group)

Notes

Not implemented.

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

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() __posixc_fclose() fileno()

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() __posixc_fputc() putc()

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

__posixc_fsetpos()

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

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.

Synopsis

void flockfile(
   FILE *file)

Function

Obtain exclusive access to the file.

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

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

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

__posixc_fgetpos()

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

__posixc_stat()

Synopsis

int fsync(
   int fd)

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

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

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

Synopsis

void funlockfile(
   FILE *file)

Function

Relinquish exclusive access to the file.

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

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() __posixc_fputc() putc()

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() __posixc_fputc() putc()

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

Synopsis

gid_t getegid(
   void)

Function

Returns the effective group ID of the calling process

See also

setgid()

Synopsis

uid_t geteuid(
   void)

See also

getuid()

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

Synopsis

gid_t getgid(
   void)

Function

Returns the real group ID of the calling process

See also

setgid()

Synopsis

struct group *getgrent(
   void)

Notes

Not implemented.

Synopsis

struct group *getgrgid(
   gid_t gid)

Notes

Not implemented.

Synopsis

struct group *getgrnam(
   const char *name)

Notes

Not implemented.

Synopsis

int getgroups(
   int gidsetlen,
   gid_t *gidset)

Notes

Not implemented.

Synopsis

int getloadavg(
   double loadavg[],
   int n)

Notes

Not implemented.

Synopsis

char * getlogin(
   )

Notes

Not implemented.

Synopsis

int getopt(
   int nargc,
   char * const nargv[],
   const char *ostr)

Notes

Due to the usage of global variables this function is now put in
the static link library. This means each compilation unit using
getopt has its own getopt state tracking.

See also

getopt_long()

Synopsis

int getopt_long(
   int nargc,
   char * const *nargv,
   const char *options,
   const struct option *long_options,
   int *idx)

Function

The getopt_long() function is similar to getopt() but it accepts options
in two forms: words and characters.  The getopt_long() function provides
a superset of the functionality of getopt(3).  The getopt_long() function
can be used in two ways.  In the first way, every long option understood
by the program has a corresponding short option, and the option structure
is only used to translate from long options to short options.  When used
in this fashion, getopt_long() behaves identically to getopt(3).  This is
a good way to add long option processing to an existing program with the
minimum of rewriting.

In the second mechanism, a long option sets a flag in the option struc-
ture passed, or will store a pointer to the command line argument in the
option structure passed to it for options that take arguments.  Addition-
ally, the long option's argument may be specified as a single argument
with an equal sign, e.g.,

   myprogram --myoption=somevalue

When a long option is processed, the call to getopt_long() will return 0.
For this reason, long option processing without shortcuts is not back-
wards compatible with getopt(3).

It is possible to combine these methods, providing for long options pro-
cessing with short option equivalents for some options.  Less frequently
used options would be processed as long options only.

The getopt_long() call requires a structure to be initialized describing
the long options.       The structure is:

   struct option {
           char *name;
           int has_arg;
           int *flag;
           int val;
   };

The name field should contain the option name without the leading double
dash.

The has_arg field should be one of:

   no_argument        no argument to the option is expect
   required_argument  an argument to the option is required
   optional_argument  an argument to the option may be presented.

If flag is not NULL, then the integer pointed to by it will be set to the
value in the val field.  If the flag field is NULL, then the val field
will be returned.       Setting flag to NULL and setting val to the corre-
sponding short option will make this function act just like getopt(3).

If the longindex field is not NULL, then the integer pointed to by it
will be set to the index of the long option relative to longopts.

The last element of the longopts array has to be filled with zeroes.

Inputs

See above

Result

If the flag field in struct option is NULL, getopt_long() and
getopt_long_only() return the value specified in the val field, which is
usually just the corresponding short option.  If flag is not NULL, these
functions return 0 and store val in the location pointed to by flag.
These functions return `:' if there was a missing option argument, `?' if
the user specified an unknown or ambiguous option, and -1 when the argu-
ment list has been exhausted.

Notes

Due to the usage of global variables this function is now put in
the static link library. This means each compilation unit using
getopt_long has its own getopt_long state tracking.

See also

getopt()

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

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.

Synopsis

pid_t getpgid(
   pid_t pid)

Function

Returns the process group ID for the specified process with ID 'pid'.

Synopsis

pid_t getpgrp(
   void)

Notes

Not implemented.

Synopsis

pid_t getpid(
   )

Function

Returns the process ID of the calling process

Result

The process ID of the calling process.

Synopsis

pid_t getppid(
   void)

Function

Returns the Parent process ID of the calling processes.

Synopsis

struct passwd *getpwent(
   void)

Notes

Not implemented.

Synopsis

struct passwd *getpwnam(
   const char *name)

Notes

Not implemented.

Synopsis

struct passwd *getpwuid(
   uid_t uid)

Function

Returns the database entry for the user with specified uid.

Notes

Function is not re-entrant. Results will be overwritten by
subsequent calls.

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

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.library/asctime() stdc.library/localtime() stdc.library/time()

Synopsis

uid_t getuid(
   void)

Function

Returns the real user ID of the calling process.

See also

geteuid()

Synopsis

int getw(
   FILE *stream)

Notes

Implemented as static inline function.
This is not a POSIX function, please use standard fread() function.

See also

__posixc_fread()

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.

Synopsis

int isatty(
   int fd)

Synopsis

long jrand48(
   unsigned short xseed[3])

Synopsis

int kill(
   pid_t pid,
   int   sig)

Notes

Not implemented.

Synopsis

void lcong48(
   unsigned short p[7])

Synopsis

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

Notes

Not implemented.

Synopsis

long lrand48(
   void)

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

__posixc_fopen() __posixc_fwrite()

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

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() __posixc_stat() umask()

Synopsis

int mknod(
   const char *pathname,
   mode_t mode,
   dev_t dev)

Notes

Not implemented.

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.

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.

Synopsis

long mrand48(
   void)

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.

Synopsis

long nrand48(
   unsigned short xseed[3])

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

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() __posixc_readdir() closedir() rewinddir() seekdir() telldir()

Synopsis

int pclose(
   FILE * stream)

Notes

Not implemented.

See also

popen()

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.

Synopsis

int pipe(
   int *pipedes)

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

__posixc_fclose() __posixc_fread() __posixc_fwrite() pipe() pclose()

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/malloc_align() stdc.library/calloc() stdc.library/free() stdc.library/malloc()

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)

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

__posixc_fputc()

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.

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

__posixc_fwrite()

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

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

Synopsis

char *realpath(
   const char *path, char *resolved_path)

Notes

Not implemented.

Synopsis

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

Synopsis

int rename(
   const char * oldpath
   const char * newpath

Function

Renames a file or directory.

Inputs

oldpath - Complete path to existing file or directory.
newpath - Complete path to the new file or directory.

Result

0 on success and -1 on error. In case of an error, errno is set.

Synopsis

void rewinddir(
   DIR *dir)

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

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

__posixc_alphasort()

Synopsis

unsigned short *seed48(
   unsigned short xseed[3])

Synopsis

void seekdir(
   DIR *dir,
   off_t offset)

Synopsis

int select(
   int nfds,
           fd_set *restrict readfds,
   fd_set *restrict writefds,
           fd_set *restrict exceptfds,
   struct timeval *restrict timeout)

Synopsis

int setegid(
   gid_t gid)

Function

Set the effective group id of the calling process to gid.

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.

Synopsis

int seteuid(
   uid_t uid)

Notes

Does not check permissions.

Synopsis

int setgid(
   gid_t gid)

Function

Set the group id, and effective group id of the calling process to gid.

Synopsis

void setgrent(
   void)

Notes

Not implemented.

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

__posixc_setvbuf()

Synopsis

void setpwent(
   void)

Notes

Not implemented.

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

Synopsis

pid_t setsid(
   void)

Function

Returns the process group ID for the new session.

Synopsis

int setuid(
   uid_t uid)

Function

Sets the user ID, and effective user ID of the calling process.

Notes

Does not check permissions.

Synopsis

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

Notes

Not implemented.

Synopsis

int sigaddset(
   sigset_t *set,
   int signum)

Synopsis

int sigdelset(
   sigset_t *set,
   int signum)

Synopsis

int sigemptyset(
   sigset_t *set)

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)

Synopsis

int sigismember(
   const sigset_t *set,
   int signum)

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

Synopsis

int sigpending(
   sigset_t *set)

Notes

Not implemented.

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.

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

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

Synopsis

void srand48(
   long seed)

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

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

Synopsis

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

Synopsis

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

Synopsis

long sysconf(
   int name)

Notes

Currently only _SC_ARG_MAX handling is implemented

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

Synopsis

pid_t tcgetpgrp(
   int fd)

Function

Returns the process group ID for the specified file descriptor.

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

Synopsis

long telldir(
   DIR *dir)

Synopsis

char * tempnam(
   const char *dir,
   const char *pfx)

Synopsis

clock_t times(
   struct tms *tms)

Notes

Not implemented.

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

Synopsis

char * ttyname(
   int fd)

Notes

Not implemented.

Synopsis

mode_t umask(
   mode_t numask)

Notes

umask is currently remembered but not used in any function

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.

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

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.

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.

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

Synopsis

int utime(
   const char *filename,
   const struct utimbuf *buf)

Function

Change last access and last modification time of the given file to
times specified in given utimbuf structure. If buf is NULL, the
current time will be used instead.

The utimbuf structure contains of two fields:

time_t actime;  - last access time
time_t modtime; - last modification time

Inputs

filename - Name of the file
buf - Pointer to utimbuf structure describing specified time.

Result

0 on success and -1 on error. If an error occurred, the global
variable errno is set.

Notes

This function can be used to set access and modification times with
a resolution of 1 second, use utimes() if you need better precision.

Bugs

Since AROS has no notion of last access time, actime field is silently
ignored, only modification time of the file is set.

See also

utimes()

Synopsis

int utimes(

   const char *file,
   const struct timeval tvp[2])

Function

Change last access and last modification time of the given file to
times specified in tvp array. If tvp is NULL, the current time will be
used instead.

Inputs

filename - Name of the file
buf - Pointer to an array of two timeval structures. First structure
        specifies the last access time, second specifies the last
        modification time

Result

0 on success and -1 on error. If an error occurred, the global
variable errno is set.

Notes

The timeval structure has microsecond resolution, but in reality
this function has time resolution of 1 tick.

Bugs

Since AROS has no notion of last access time, it's silently ignored
and only modification time of the file is set.

See also

utime()

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

Synopsis

pid_t wait(
   int *status)

Function

Waits for child process to change state. State change is one of the
following events: child has exited, child was terminated by a signal,
child was stopped by a signal, child was resumed by a signal.

The function stores status of the process that changed state in the
pointer given as status argument.

The following macros can be used to extract information from the
status value:

WIFEXITED(status)    - true if the process has exited
WEXITSTATUS(status)  - exit status of the exited process
WIFSIGNALED(status)  - true if the child process was terminated by a
                       signal
WTERMSIG(status)     - number of the signal that caused process
                       termination
WIFSTOPPED(status)   - true if the child process was stopped by a
                       signal
WSTOPSIG(status)     - number of the signal that caused child process
                       stop
WIFCONTINUED(status) - true if the child process was resumed by the
                       SIGCONT signal.

Parent process will be suspended until a child changes state. If a
child process has already changed state, function returns immediately.

Inputs

status - Pointer to int where child return status will be stored or
NULL if you don't want to store status.

Result

Process id of the child process on success or -1 on error. If an error
occurred, the global variable errno is set.

Notes

This function will work only for child processes notifying parent
process of their death, for example processes created by vfork() call.
If you want to use it for other processes, remember to set the
NP_NotifyOnDeath tag value to TRUE during child process creation.

See also

waitpid()

Synopsis

pid_t waitpid(
   pid_t pid,
   int *status,
   int options)

Function

Waits for child process with given process id to change state. State
change is one of the following events: child has exited, child was
terminated by a signal, child was stopped by a signal, child was
resumed by a signal.

The function stores status of the process that changed state in the
pointer given as status argument.

The following macros can be used to extract information from the
status value:

WIFEXITED(status)    - true if the process has exited
WEXITSTATUS(status)  - exit status of the exited process
WIFSIGNALED(status)  - true if the child process was terminated by a
                       signal
WTERMSIG(status)     - number of the signal that caused process
                       termination
WIFSTOPPED(status)   - true if the child process was stopped by a
                       signal
WSTOPSIG(status)     - number of the signal that caused child process
                       stop
WIFCONTINUED(status) - true if the child process was resumed by the
                       SIGCONT signal.

Unless WNOHANG option is set, parent process will be suspended until a
child changes state. If a child process has already changed state,
function returns immediately.

Inputs

pid - Process id of the process you want to wait for or -1 to wait for
        any child process
status - Pointer to int where child status will be stored or NULL if
        you don't want to store status.
options - ORed zero or more of the following constants:

    WNOHANG - return immediately if no child process changed state

Result

Process id of the child process on success or -1 on error. If an error
occurred, the global variable errno is set.

Notes

This function will work only for child processes notifying parent
process of their death, for example processes created by vfork() call.
If you want to use it for other processes, remember to set the
NP_NotifyOnDeath tag value to TRUE during child process creation.

See also

wait()

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.