__posixc_fopen()

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.

__posixc_fprintf()

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.

__posixc_fputc()

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.

__posixc_fputs()

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.

__posixc_fread()

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.

__posixc_freopen()

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 compatible
         with the mode of the file  descriptor.   The  file
         position  indicator  of  the  new  stream  is  set to that
         belonging to fildes, and the error and end-of-file indicators
         are cleared.  Modes "w" or "w+" do not cause truncation of the
         file.  The file descriptor is not duplicated,  and
         will  be  closed  when  the  stream  created  by fdopen is
         closed.
stream - the stream to which the file will be associated.

Result

NULL on error or stream.

__posixc_fscanf()

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.

__posixc_fseek()

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.

__posixc_fseeko()

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

__posixc_fsetpos()

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.

__posixc_fstat()

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.

__posixc_ftell()

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.

__posixc_ftello()

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.

__posixc_fwrite()

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.

__posixc_getchar()

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.

__posixc_getenv()

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.

__posixc_gets()

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.

__posixc_lseek()

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.

__posixc_lstat()

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.

__posixc_printf()

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.