posixc
Index
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.
int __get_default_file(
int file_descriptor,
long * file_handle)
Gets dos.library file handle associated with a given file descriptor.
file_descriptor - the File Descriptor you wish to obtain the associated
file handle for.
file_handle - Pointer to store the associated file handle.
!=0 on error, 0 on success.
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.
const char *__path_a2u(
const char *apath)
Translates an AmigaDOS-style path into an unix one.
apath - AmigaDOS-style path to translate into an unix-style equivalent.
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.
This function is for private usage by system code. Do not use it
elsewhere.
const char *__path_u2a(
const char *upath)
Translates a unix-style path into an AmigaDOS one.
upath - Unix-style path to translate into an AmigaDOS-style equivalent.
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.
This function is for private usage by system code. Do not use it
elsewhere.
int __posixc_alphasort(
const struct dirent **a,
const struct dirent **b
)
Support function for scandir().
void __posixc_assert(
const char * expr,
const char * file,
unsigned int line)
This is a function that is used for implementation of the C99 assert()
function.
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.
The function doesn't return.
Different versions of this function are available. This function
is used when a program is using posixc.library.
int __posixc_creat(
const char * pathname,
int mode)
Creates a file with the specified mode and name.
pathname - Path and filename of the file you want to open.
mode - The access flags.
-1 for error or a file descriptor for use with write().
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.
int __posixc_fclose(
FILE * stream)
stream - Stream to close.
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.
int __posixc_feof(
FILE * stream)
Test the EOF-Flag of a stream. This flag is set automatically by
any function which recognizes EOF. To clear it, call clearerr().
stream - The stream to be tested.
!= 0, if the stream is at the end of the file, 0 otherwise.
This function must not be used in a shared library or
in a threaded application.
int __posixc_ferror(
FILE * stream)
Test the error flag of a stream. This flag is set automatically by
any function that detects an error. To clear it, call clearerr().
stream - The stream to be tested.
!= 0, if the stream had an error, 0 otherwise.
int __posixc_fflush(
FILE * stream)
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.
stream - Flush this stream. May be NULL. In this case, all
output streams are flushed.
0 on success or EOF on error.
int __posixc_fgetpos(
FILE * stream,
fpos_t * pos)
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.
stream - The stream to get the position from.
pos - Pointer to the fpos_t position structure to fill.
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
char * __posixc_fgets(
char * buffer,
int size,
FILE * stream)
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).
buffer - Write characters into this buffer
size - This is the size of the buffer in characters.
stream - Read from this stream
buffer or NULL in case of an error or EOF.
// Read a file line by line
char line[256];
// Read until EOF
while (fgets (line, sizeof (line), fh))
{
// Evaluate the line
}
FILE * __posixc_fopen(
const char * pathname,
const char * mode)
Opens a file with the specified name in the specified mode.
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.
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.
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.
Most modes are not supported right now.
int __posixc_fprintf(
FILE * fh,
const char * format,
...)
Format a string with the specified arguments and write it to
the stream.
fh - Write to this stream
format - How to format the arguments
... - The additional arguments
The number of characters written to the stream or EOF on error.
int __posixc_fputc(
int c,
FILE * stream)
Write one character to the specified stream.
c - The character to output
stream - The character is written to this stream
The character written or EOF on error.
int __posixc_fputs(
const char * str,
FILE * stream)
Write a string to the specified stream.
str - Output this string...
fh - ...to this stream
> 0 on success and EOF on error.
size_t __posixc_fread(
void * buf,
size_t size,
size_t nblocks,
FILE * stream)
Read an amount of bytes from a stream.
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
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.
FILE *__posixc_freopen(
const char *path,
const char *mode,
FILE *stream
)
Opens the file whose name is the string pointed to by path and
associates the stream pointed to by stream with it.
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.
int __posixc_fscanf(
FILE * fh,
const char * format,
...)
Scan a string with the specified arguments and write the results
in the specified parameters.
fh - Read from this stream
format - How to convert the input into the arguments
... - Write the result in these arguments
The number of converted arguments.
int __posixc_fseek(
FILE * stream,
long offset,
int whence)
Change the current position in a stream.
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).
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
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.
int __posixc_fseeko(
FILE * stream,
off_t offset,
int whence)
Change the current position in a stream.
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).
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
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.
Not fully compatible with ISO fseeko, especially in 'ab' and 'a+b'
modes
int __posixc_fsetpos(
FILE * stream,
const fpos_t * pos)
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.
stream - Modify this stream
pos - The new position in the stream.
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
int __posixc_fstat(
int fd,
struct stat *sb)
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.
filedes - File descriptor of the file
sb - Pointer to stat structure that will be filled by the fstat()
call.
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
long __posixc_ftell(
FILE * stream)
Tell the current position in a stream.
stream - Obtain position of this stream
The position on success and -1 on error.
If an error occurred, the global variable errno is set.
off_t __posixc_ftello(
FILE *stream)
Returns the current position in a stream.
stream - Query this stream
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.
size_t __posixc_fwrite(
const void * restrict buf,
size_t size,
size_t nblocks,
FILE * restrict stream)
Write an amount of bytes to a stream.
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
The number of blocks written. If no error occurred, this is
nblocks. Otherwise examine errno for the reason of the error.
Read one character from the standard input stream. If there
is no character available or an error occurred, the function
returns EOF.
The character read or EOF on end of file or error.
char *__posixc_getenv(
const char *name)
Get an environment variable.
name - Name of the environment variable.
Pointer to the variable's value, or NULL on failure.
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.
char * __posixc_gets(
char * buffer)
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'.
buffer - Write characters into this buffer
buffer or NULL in case of an error or EOF.
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.
off_t __posixc_lseek(
int filedes,
off_t offset,
int whence)
Reposition read/write file offset
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).
The new position on success and -1 on error. If an error occurred, the global
variable errno is set.
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.
int __posixc_lstat(
const char *path,
struct stat *sb)
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.
path - Pathname of the file
sb - Pointer to stat structure that will be filled by the lstat() call.
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
int __posixc_printf(
const char * format,
...)
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.
format - Format string as described above
... - Arguments for the format string
The number of characters written to stdout or EOF on error.
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);
}
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.
int __posixc_putchar(
int c)
int __posixc_puts(
const char * str)
Print a string to stdout. A newline ('\n') is emitted after the
string.
> 0 on success and EOF on error. On error, the reason is put in
errno.
#include <errno.h>
if (puts ("Hello World.") != EOF)
fprintf (stderr, "Success");
else
fprintf (stderr, "Failure: errno=%d", errno);
struct dirent *__posixc_readdir(
DIR *dir)
dir - the directory stream pointing to the directory being read
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.
void __posixc_rewind(
FILE * stream)
Change the current position in a stream to the beginning.
stream - Modify this stream
int __posixc_scandir(
const char *dir,
struct dirent ***namelist,
int (*select)(const struct dirent *),
int (*compar)(const struct dirent **, const struct dirent **)
)
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.
int __posixc_scanf(
const char * format,
...)
The number of converted parameters
void __posixc_setbuf(
FILE *stream,
char *buf)
This is a simpler alias for setvbuf() according to manpage.
int __posixc_setvbuf(
FILE *stream,
char *buf,
int mode,
size_t size)
int __posixc_stat(
const char *path,
struct stat *sb)
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
path - Pathname of the file
sb - Pointer to stat structure that will be filled by the stat() call.
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
char * __posixc_strerror(
int n)
Returns a readable string for an error number in errno.
n - The contents of errno or a #define from errno.h
A string describing the error.
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
int __posixc_system(
const char *string)
Execute a command string. If string is NULL then 1 will be returned.
string - command to execute or NULL
Return value of command executed. If value < 0 errno indicates error.
1 is return if string is NULL.
The system() version of posixc.library will translate UNIX<>Amiga
if applicable as well as use a shell for executing text batch
commands.
FILE * __posixc_tmpfile(
void)
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.
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().
#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");
}
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.
char *__posixc_tmpnam(
char *s)
int __posixc_ungetc(
int c,
FILE * stream)
Push the character c character back into the stream.
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
int __posixc_vfprintf(
FILE * stream,
const char * format,
va_list args)
Format a list of arguments and print them on the specified stream.
stream - A stream on which one can write
format - A printf() format string.
args - A list of arguments for the format string.
The number of characters written.
int __posixc_vfscanf(
FILE * stream,
const char * format,
va_list args)
Read the scream, scan it as the format specified and write the
result of the conversion into the specified arguments.
stream - A stream to read from
format - A scanf() format string.
args - A list of arguments for the results.
The number of converted arguments.
int __posixc_vprintf(
const char * format,
va_list args)
Format a list of arguments and print them on the standard output.
format - A printf() format string.
args - A list of arguments for the format string.
The number of characters written.
int __posixc_vscanf(
const char * format,
va_list args)
Scan the standard input and convert it into the arguments as
specified by format.
format - A scanf() format string.
args - A list of arguments for the results
The number of converted parameters.
int access(
const char *path,
int mode)
Check access permissions of a file or pathname
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
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.
int alphasort64(
const struct dirent64 **a,
const struct dirent64 **b
)
Support function for scandir64().
char *basename(
char *filename)
Returns the part after the latest '/' of a path.
Trailing '/' are not counted as part of the path.
filename - Path which should be split.
Rightmost part of the path.
int chdir(
const char *path )
Change the current working directory to the one specified by path.
path - Path of the directory to change to.
If the current directory was changed successfully, zero is returned.
Otherwise, -1 is returned and errno set appropriately.
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:).
int chmod(
const char *path,
mode_t mode)
Change permission bits of a specified file.
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
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
S_ISUID and S_ISGID are silently ignored.
int chown(
const char *path,
uid_t owner,
gid_t group)
Change the user and group ownership of a file.
path - the path to file
owner - new owner ID
group - new group ID
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
This implementation was done by looking at Olaf 'Olsen' Barthels
clib2.
void clearerr(
FILE * stream)
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.
stream - The stream to be reset.
int clock_gettime(
clockid_t clk_id,
struct timespec *tp)
retrieve the time of the specified clock clk_id.
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
0 on success, -1 on error
Currently at most a resolution of milliseconds is supported.
Closes an open file. If this is the last file descriptor
associated with this file, then all allocated resources
are freed, too.
fd - The result of a successful open()
-1 for error or zero on success.
This function must not be used in a shared library or
in a threaded application.
dir - the directory stream pointing to the directory being closed
The closedir() function returns 0 on success or -1 on
failure.
int creat64(
const char * pathname,
int mode)
Creates a file with the specified mode and name.
pathname - Path and filename of the file you want to open.
mode - The access flags.
-1 for error or a file descriptor for use with write().
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.
get directory stream file descriptor
dir - directory stream dir.
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.
char *dirname(
char *filename)
Returns the string up to the latest '/'.
filename - Path which should be split
Directory part of the path.
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.
oldfd - The file descriptor to be duplicated
-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.
This function must not be used in a shared library or
in a threaded application.
int dup2(
int oldfd,
int newfd
)
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.
oldfd - The file descriptor to be duplicated
newfd - The value of the new descriptor we want the old one to be
duplicated in
-1 for error or newfd on success
This function must not be used in a shared library or
in a threaded application.
int execl(
const char *path,
const char *arg, ...)
Executes a file located in given path with specified arguments.
path - Pathname of the file to execute.
arg - First argument passed to the executed file.
... - Other arguments passed to the executed file.
Returns -1 and sets errno appropriately in case of error, otherwise
doesn't return.
int execlp(
const char *file,
const char *arg, ...)
Executes a file with given name. The search paths for the executed
file are paths specified in the PATH environment variable.
file - Name of the file to execute.
arg - First argument passed to the executed file.
... - Other arguments passed to the executed file.
Returns -1 and sets errno appropriately in case of error, otherwise
doesn't return.
int execv(
const char *path,
char *const argv[])
Executes a file located in given path with specified arguments.
path - Pathname of the file to execute.
argv - Array of arguments given to main() function of the executed
file.
Returns -1 and sets errno appropriately in case of error, otherwise
doesn't return.
int execve(
const char *filename,
char *const argv[],
char *const envp[])
Executes a file with given name.
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.
Returns -1 and sets errno appropriately in case of error, otherwise
doesn't return.
int execvp(
const char *file,
char *const argv[])
Executes a file with given name. The search paths for the executed
file are paths specified in the PATH environment variable.
file - Name of the file to execute.
argv - Array of arguments given to main() function of the executed
file.
Returns -1 and sets errno appropriately in case of error, otherwise
doesn't return.
Change the current working directory to the directory given as an open
file descriptor.
fd - File descriptor of the directory to change to.
If the current directory was changed successfully, zero is returned.
Otherwise, -1 is returned and errno set appropriately.
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.
int fchmod(
int filedes,
mode_t mode)
Change permission bits of a file specified by an open file descriptor.
filedes - File descriptor of the file
mode - Permission bits to set
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
See chmod() documentation for more details about the mode parameter.
int fchown(
int fd,
uid_t owner,
gid_t group)
int fcntl(
int fd,
int cmd,
...)
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.
fd - File descriptor to perform operation on.
cmd - Operation specifier.
... - Operation arguments.
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.
FILE *fdopen(
int filedes,
const char *mode
)
function associates a stream with an existing file descriptor.
filedes - The descriptor the stream has to be associated with
mode - The mode of the stream (same as with fopen()) must be compatible
with the mode of the file descriptor. The file
position indicator of the new stream is set to that
belonging to filedes, and the error and end-of-file indicators
are cleared. Modes "w" or "w+" do not cause truncation of the
file. The file descriptor is not duplicated, and
will be closed when the stream created by fdopen is
closed.
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.
Read one character from the stream. If there is no character
available or an error occurred, the function returns EOF.
stream - Read from this stream
The character read or EOF on end of file or error.
int fgetpos64(
FILE * stream,
__fpos64_t * pos)
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.
stream - The stream to get the position from.
pos - Pointer to the fpos_t position structure to fill.
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
int fileno(
FILE *stream)
Returns the descriptor associated with the stream
strem - the stream to get the descriptor from
int flock(
int fd,
int operation)
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.
fd - File descriptor of the file you want to place or remove lock from.
operation - Lock operation to be performed.
0 on success, -1 on error. In case of error a global errno variable
is set.
Locks placed with flock() are only advisory, they place no
restrictions to any file or file descriptor operations.
It's currently possible to remove lock placed by another process.
void flockfile(
FILE *file)
Obtain exclusive access to the file.
FILE * fopen64(
const char * pathname,
const char * mode)
Opens a file with the specified name in the specified mode.
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.
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.
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.
Most modes are not supported right now.
int fseeko64(
FILE * stream,
off64_t offset,
int whence)
Change the current position in a stream.
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).
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
Allows seeking on files that may be larger than 2GB, if the
underlying filesystem supports it.
Not fully compatible with ISO fseeko, especially in 'ab' and 'a+b'
modes
int fsetpos64(
FILE * stream,
const __fpos64_t * pos)
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.
stream - Modify this stream
pos - The new position in the stream.
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
int fstat64(
int fd,
struct stat64 *sb)
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.
filedes - File descriptor of the file
sb - Pointer to stat structure that will be filled by fstat64()
call.
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
off64_t ftello64(
FILE *stream)
Returns the current position in a stream.
stream - Query this stream
Returns the position in files that may be larger than 2 GB, if the
underlying filesystem supports it.
int ftime(
struct timeb *tb)
Get info on current time and timezone.
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.
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.
int ftruncate(
int fd,
off_t length)
Truncate a file to a specified length
fd - the descriptor of the file being truncated.
The file must be open for writing
lenght - The file will have at most this size
0 on success or -1 on errorr.
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.
void funlockfile(
FILE *file)
Relinquish exclusive access to the file.
char * gcvt(
double number,
int ndigit,
char * buf
)
Converts a number to a minimal length NULL terminated ASCII string.
It produces ndigit significant digits in either printf F format or
E format.
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.
The address of the string pointed to by buf.
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.
Read one character from the stream. If there is no character
available or an error occurred, the function returns EOF.
stream - Read from this stream
The character read or EOF on end of file or error.
int getc_unlocked(
FILE * stream)
stream - Read from this stream
The character read or EOF on end of file or error.
char *getcwd(
char *buf,
size_t size)
Get the current working directory.
buf - Pointer of the buffer where the path is to be stored
size - The size of the above buffer
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.
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.
Returns the effective group ID of the calling process
int getfsstat(
struct statfs *buf,
long bufsize,
int flags)
Gets information about mounted filesystems.
buf - pointer to statfs structures where information about filesystems
will be stored or NULL
bufsize - size of buf in bytes
flags - not used
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
f_flags, f_files, f_ffree and f_fsid.val are always set to 0
f_mntfromname is set to an empty string
Returns the real group ID of the calling process
struct group *getgrent(
void)
struct group *getgrgid(
gid_t gid)
struct group *getgrnam(
const char *name)
int getgroups(
int gidsetlen,
gid_t *gidset)
int getloadavg(
double loadavg[],
int n)
int getopt(
int nargc,
char * const nargv[],
const char *ostr)
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.
int getopt_long(
int nargc,
char * const *nargv,
const char *options,
const struct option *long_options,
int *idx)
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.
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.
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.
int getopt_long_only(
int nargc,
char * const *nargv,
const char *options,
const struct option *long_options,
int *idx)
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.
char * getpass(
const char *prompt)
(obsolete) prompt for a password.
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.
pid_t getpgid(
pid_t pid)
Returns the process group ID for the specified process with ID 'pid'.
Returns the process ID of the calling process
The process ID of the calling process.
Returns the Parent process ID of the calling processes.
struct passwd *getpwent(
void)
struct passwd *getpwnam(
const char *name)
struct passwd *getpwuid(
uid_t uid)
Returns the database entry for the user with specified uid.
Function is not re-entrant. Results will be overwritten by
subsequent calls.
int getrlimit(
int resource,
struct rlimit *rlp)
Get the limits of certain system resources
resource - the resource type to get
rlp - returned resource information
On success, returns 0. -1 and errno on error.
int gettimeofday(
struct timeval * tv,
struct timezone * tz)
Return the current time and/or timezone.
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
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);
This function must not be used in a shared library or
in a threaded application.
Returns the real user ID of the calling process.
Implemented as static inline function.
This is not a POSIX function, please use standard fread() function.
int ioctl(
int fd,
int request,
...)
Control device. Function to manipulate and fetch special device
parameters.
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
EBADF - fd is not valid
EFAULT - no valid argument
ENOTTY - fd is not of required type
#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);
}
}
Width and height are the width and height of the intuition window.
Only the requests listed above are implemented.
long jrand48(
unsigned short xseed[3])
int kill(
pid_t pid,
int sig)
void lcong48(
unsigned short p[7])
int link(
const char *oldpath,
const char *newpath)
__off64_t lseek64(
int filedes,
__off64_t offset,
int whence)
Reposition read/write file offset
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).
The new position on success and -1 on error. If an error occurred, the global
variable errno is set.
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.
int lstat64(
const char *path,
struct stat64 *sb)
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.
path - Pathname of the file
sb - Pointer to stat structure that will be filled by the lstat() call.
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
int mkdir(
const char *path,
mode_t mode)
path - the path of the directory being created
mode - the permission flags for the directory
0 on success or -1 on errorr.
int mknod(
const char *pathname,
mode_t mode,
dev_t dev)
int mkstemp(
char *template)
A template that must end with 'XXXXXX'
A file descriptor of opened temporary file or -1 on error.
char *mktemp(
char *template)
Make a unique temporary file name.
template - template to change into unique filename
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 .
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.
int nanosleep(
const struct timespec * req, struct timespec *rem)
Suspends program execution for a given number of nanoseconds.
req - time to wait
rem - remaining time, if nanosleep was interrupted by a signal
0 on success, -1 on error
Currently at most a resolution of milliseconds is supported.
long nrand48(
unsigned short xseed[3])
int open(
const char * pathname,
int flags,
...)
Opens a file with the specified flags and name.
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.
-1 for error or a file descriptor for use with read(), write(), etc.
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.
The flag O_EXCL is not very reliable if the file resides on a NFS
filesystem.
Most flags are not supported right now.
DIR *opendir(
const char *name)
pathname - Path and filename of the directory you want to open.
NULL for error or a directory stream
int pclose(
FILE * stream)
void perror(
const char *string
)
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.
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.
FILE * popen(
const char * command,
const char * mode)
"opens" a process by creating a pipe, spawning a new process and invoking
the shell.
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.
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.
This function must not be used in a shared library or
in a threaded application.
int posix_memalign(
void **memptr,
size_t alignment,
size_t size)
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.
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.
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.
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)
int putc(
int c,
FILE * stream)
Write one character to the specified stream.
c - The character to output
stream - The character is written to this stream
The character written or EOF on error.
int putenv(
const char *string)
Change or add an environment variable.
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.
The putenv() function returns zero on success, or -1 if an
error occurs. In such a case the errno variable is set
appropriately.
This function must not be used in a shared library.
Conforming to BSD4.4 in that it makes a copy of the argument string.
int putw(
int word,
FILE *stream)
Implemented as static inline function.
This is not a POSIX function, please use standard fwrite() function.
ssize_t read(
int fd,
void * buf,
size_t count)
Read an amount of bytes from a file descriptor.
fd - The file descriptor to read from
buf - The buffer to read the bytes into
count - Read this many bytes.
The number of characters read (may range from 0 when the file
descriptor contains no more characters to count) or -1 on error.
struct dirent64 *readdir64(
DIR *dir)
dir - the directory stream pointing to the directory being read
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.
char *realpath(
const char *path, char *resolved_path)
int remove(
const char * pathname)
Deletes a file or directory.
pathname - Complete path to the file or directory.
0 on success and -1 on error. In case of an error, errno is set.
int rename(
const char * oldpath
const char * newpath
Renames a file or directory.
oldpath - Complete path to existing file or directory.
newpath - Complete path to the new file or directory.
0 on success and -1 on error. In case of an error, errno is set.
void rewinddir(
DIR *dir)
int rmdir(
const char * pathname)
Deletes an empty directory.
pathname - Complete path to the directory.
0 on success and -1 on error. In case of an error, errno is set.
int scandir64(
const char *dir,
struct dirent64 ***namelist,
int (*select)(const struct dirent64 *),
int (*compar)(const struct dirent64 **, const struct dirent64 **)
)
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.
unsigned short *seed48(
unsigned short xseed[3])
void seekdir(
DIR *dir,
off_t offset)
int select(
int nfds,
fd_set *restrict readfds,
fd_set *restrict writefds,
fd_set *restrict exceptfds,
struct timeval *restrict timeout)
Set the effective group id of the calling process to gid.
int setenv(
const char *name,
const char *value,
int overwrite)
Change or add an environment variable.
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
Returns zero on success, or -1 if there was insufficient
space in the environment.
This function must not be used in a shared library.
Does not check permissions.
Set the group id, and effective group id of the calling process to gid.
void setlinebuf(
FILE *stream)
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.
int setrlimit(
int resource,
const struct rlimit *rlp)
Get the limits of certain system resources
resource - the resource type to get
rlp - resource information to update
On success, returns 0. -1 and errno on error.
Currently always returns -1 and errno is set to EINVAL
Returns the process group ID for the new session.
Sets the user ID, and effective user ID of the calling process.
Does not check permissions.
int sigaction(
int signum,
const struct sigaction *act,
struct sigaction *oldact)
int sigaddset(
sigset_t *set,
int signum)
int sigdelset(
sigset_t *set,
int signum)
int sigemptyset(
sigset_t *set)
int sigfillset(
sigset_t *set)
Initialise the signal set
"0" for success, "-1" for failure (errno contains error)
int sigismember(
const sigset_t *set,
int signum)
void siglongjmp(
jmp_buf env,
int val)
Save the current context so that you can return to it later.
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.
This function doesn't return.
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) ...
}
int sigpending(
sigset_t *set)
int sigprocmask(
int how,
const sigset_t *set,
sigset_t *oldset)
Allow the caller to examine or change (or both) the
signal mask of the calling thread.
int sigsuspend(
const sigset_t *mask)
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.
always returns -1, normally with the error EINTR.
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()
unsigned int sleep(
unsigned int seconds )
The sleep() function makes the current process sleep for the
specified number of seconds or until a signal arrives which
is not ignored.
seconds - The number of seconds to sleep
Zero if the requested time has elapsed, or the number of seconds
left to sleep when the process was signaled.
// Sleep for 10 seconds
sleep( 10 );
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).
int stat64(
const char *path,
struct stat64 *sb)
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
path - Pathname of the file
sb - Pointer to stat structure that will be filled by the stat() call.
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
int statfs(
const char *path,
struct statfs *buf)
Gets information about mounted filesystem.
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
Information about filesystem is stored in statfs structure
f_flags, f_files, f_ffree and f_fsid.val are always set to 0
f_mntfromname is set to an empty string
void swab(
const void *from,
void *to,
size_t len)
int symlink(
const char *oldpath,
const char *newpath)
Currently only _SC_ARG_MAX handling is implemented
int tcgetattr(
int fd,
struct termios *t)
fd - file descriptor
t - struct termios where attributes are put
Currently supports only ICANON flag
Returns the process group ID for the specified file descriptor.
int tcsetattr(
int fd,
int opt,
const struct termios *t)
fd - file descriptor
opt - optional actions
t - struct termios containing the requested changes
Will return success, if *any* of the changes were successful.
Currently supports only ICANON flag
char * tempnam(
const char *dir,
const char *pfx)
clock_t times(
struct tms *tms)
int truncate(
const char *path,
off_t length)
Truncate a file to a specified length
path - the path of the file being truncated
lenght - The file will have at most this size
0 on success or -1 on errorr.
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.
mode_t umask(
mode_t numask)
umask is currently remembered but not used in any function
int uname(
struct utsname *name)
Store information about the operating system in the structure pointed
to by name.
name - Pointer to utsname structure defined in <sys/utsname.h>.
If the information was stored successfully, zero is returned. Otherwise
function returns -1 and sets errno appropriately.
int unlink(
const char * pathname)
pathname - Complete path to the file
0 on success and -1 on error. In case of an error, errno is set.
// Delete the file xyz in the current directory
unlink ("xyz");
int unsetenv(
const char *name)
deletes a variable from the environment.
name -- Name of the environment variable to delete.
Returns zero on success, or -1 if the variable was not found.
Update stdin, stdout, stderr to reflect changes done by calling
dos.library functions like SelectInput(), ...
stdin, stdout and stderr will be flushed before they are updated.
int usleep(
useconds_t usec)
Suspends program execution for a given number of microseconds.
usec - number of microseconds to wait
0 on success, -1 on error
This function is not part of POSIX.1-2008 anymore. Don't use this
function. As an alternative nanosleep() can be used.
int utime(
const char *filename,
const struct utimbuf *buf)
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
filename - Name of the file
buf - Pointer to utimbuf structure describing specified time.
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
This function can be used to set access and modification times with
a resolution of 1 second, use utimes() if you need better precision.
Since AROS has no notion of last access time, actime field is silently
ignored, only modification time of the file is set.
int utimes(
const char *file,
const struct timeval tvp[2])
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.
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
0 on success and -1 on error. If an error occurred, the global
variable errno is set.
The timeval structure has microsecond resolution, but in reality
this function has time resolution of 1 tick.
Since AROS has no notion of last access time, it's silently ignored
and only modification time of the file is set.
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.
-1: error, no child is started; errno will be set.
0: Running in child
>0: Running in parent, pid of child is return value.
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.
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.
status - Pointer to int where child return status will be stored or
NULL if you don't want to store status.
Process id of the child process on success or -1 on error. If an error
occurred, the global variable errno is set.
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.
pid_t waitpid(
pid_t pid,
int *status,
int options)
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.
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
Process id of the child process on success or -1 on error. If an error
occurred, the global variable errno is set.
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.
ssize_t write(
int fd,
const void * buf,
size_t count)
Write an amount of characters to the specified file descriptor.
fd - The file descriptor to write to
buf - Write these bytes into the file descriptor
count - Write that many bytes
The number of characters written or -1 on error.
Docutils System Messages
System Message: ERROR/3 (/home/vsts/work/1/b/documentation/web/documentation/developers/autodocs/posixc.en, line 1406); backlink
Unknown target name: "__posixc_fgetc()".
System Message: ERROR/3 (/home/vsts/work/1/b/documentation/web/documentation/developers/autodocs/posixc.en, line 7432); backlink
Unknown target name: "pause()".
System Message: ERROR/3 (/home/vsts/work/1/b/documentation/web/documentation/developers/autodocs/posixc.en, line 7432); backlink
Unknown target name: "sigwaitinfo()".
System Message: ERROR/3 (/home/vsts/work/1/b/documentation/web/documentation/developers/autodocs/posixc.en, line 7432); backlink
Unknown target name: "sigsetops()".
System Message: ERROR/3 (/home/vsts/work/1/b/documentation/web/documentation/developers/autodocs/posixc.en, line 7432); backlink
Unknown target name: "sigwait()".
|
|