|
|
clib
Index
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.
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 an 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 __spawnv(
int mode,
BPTR seg,
char *const argv[])
Spawn a child process, given a vector of arguments and an already LoadSeg()'d executable.
mode - the way the child process has to be loaded, and how the parent has to behave
after the child process is initiated. Specify one of the following values:
P_WAIT - the child program is loaded into memory, then it's executed while
the parent process waits for it to terminate, at which point the
patent process resumes execution.
P_NOWAIT - the parent program is executed concurrently with the new child process.
P_OVERLAY - teplace the parent program with the child program in memory and then
execute the child. The parent program will never be resumed. This
mode is equivalent to calling one of the exec*() functions.
seg - the LoadSeg()'s executable. The segment is UnloadSeg()'d by this function.
argv - a pointer to a NULL terminated array of strings representing arguments to pass
to the child process. The first entry in the array is conventionally the name of
the program to spawn, but in any case it must _never_ be NULL, and the argv
pointer itself must never be NULL either.
If P_WAIT is specified, then the return code of the child program is returned.
If instead P_NOWAIT is used, then the pid of the newly created process is returned.
Finally, if P_OVERLAY is used, the function doesn't return unless an error has occurred,
in which case -1 is returned also for the other modes and the global errno variable will
hold the proper error code.
The way the child process behaves regarding parent's file descriptors, signal handlers
and so on is the same way it would behave with one of the exec*(3) functions.
This, for one, means that all filedescriptors are inherited except the ones which have
the close-on-exec flag set.
int __vcformat(
void * data,
int (* outc)(int, void *),
const char * format,
va_list args)
Format a list of arguments and call a function for each char
to print.
data - This is passed to the usercallback outc
outc - Call this function for every character that should be
emitted. The function should return EOF on error and
> 0 otherwise.
format - A printf() format string.
args - A list of arguments for the format string.
The number of characters written.
int __vcscan(
void * data,
int (* getc)(void *),
int (* ungetc)(int,void *),
const char * format,
va_list args)
Scan an input stream as specified in format. The result of
the scan will be placed in args.
data - This is passed to the usercallback getc and ungetc
getc - This function gets called when the routine wants to
read the next character. It whould return EOF when
no more characters are available.
ungetc - This function gets called when the routine wants to
put a read character back into the stream. The next
call to getc should return this character. It is possible
that this function is called more than once before the
next getc.
format - A scanf() format string.
args - A list of arguments in which the result of the scan should
be placed.
The number of arguments converted.
Terminates the running program immediately. The code is returned to
the program which has called the running program. In contrast to
exit(), this function does not call user exit-handlers added with
atexit() or on_exit(). It does, however, close open filehandles.
code - Exit code. 0 for success, other values for failure.
None. This function does not return.
This function must not be used in a shared library or in a threaded
application.
EXAMPLE
Currently, this function *does* trigger user exit-handlers to be
called.
Causes abnormal program termination. If there is a signal handler
for SIGABORT, then the handler will be called. If the handler
returns, then the program is continued.
None. This function does not return.
if (fatal_error)
abort ();
This function must not be used in a shared library or
in a threaded application.
Signal handling is not implemented yet.
Compute the absolute value of j.
// returns 1
abs (1);
// returns 1
abs (-1);
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 readpermissions
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.
char * asctime(
const struct tm * tm)
The asctime() function converts the broken-down time value tm
into a string.
See asctime_r() for details.
tm - The broken down time
A statically allocated buffer with the converted time. Note that
the contents of the buffer might get lost with the call of any of the
date and time functions.
time_t tt;
struct tm * tm;
char * str;
// Get time
time (&tt);
// Break time up
tm = localtime (&tt);
// Convert to string
str = asctime (tm);
This function must not be used in a shared library or
in a threaded application. Use asctime_r() instead.
char * asctime_r(
const struct tm * tm,
char * buf)
The asctime_r() function converts the broken-down time value tm
into a string with this format:
"Wed Jun 30 21:49:08 1993\n"
tm - The broken down time
buf - Buffer of at least 26 characters to store the string in
The pointer passed in buf, containing the converted time. Note that
there is a newline at the end of the buffer.
time_t tt;
struct tm tm;
char str[26];
// Get time
time (&tt);
// Break time up
localtime (&tt, &tm);
// Convert to string
asctime (&tm, str);
Evaluates the expression expr and if it's FALSE or NULL, then
printf a message and stops the program. The message will
contain the expression, the name of the file with the assert
in it and the line in the file.
expr - The expression to evaluate. The type of the expression does
not matter, only if its zero/NULL or not.
The function doesn't return.
// Make sure that x equals 1
assert (x==1);
int atexit(
void (*func)(void))
Registers the given function to be called at normal
process termination.
func - function to be called.
double atof(
const char * str)
Convert a string of digits into a double.
str - The string which should be converted. Leading
whitespace are ignored. The number may be prefixed
by a '+' or '-'.
int atoi(
const char * str)
Convert a string of digits into an integer.
str - The string which should be converted. Leading
whitespace are ignored. The number may be prefixed
by a '+' or '-'.
// returns 1
atoi (" \t +1");
// returns 1
atoi ("1");
// returns -1
atoi (" \n -1");
long atol(
const char * str)
Convert a string of digits into an long integer.
str - The string which should be converted. Leading
whitespace are ignored. The number may be prefixed
by a '+' or '-'.
// returns 1
atol (" \t +1");
// returns 1
atol ("1");
// returns -1
atol (" \n -1");
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 bcmp(
const void * s1,
const void * s2,
size_t n)
Compare the first n bytes of s1 and s2.
s1 - The first byte array to be compared
s2 - The second byte array to be compared
n - How many bytes to compare
void * bsearch(
const void * key,
const void * base,
size_t count,
size_t size,
int (* comparefunction)(const void *, const void *))
Search in a sorted array for an entry key.
key - Look for this key.
base - This is the address of the first element in the array
to be searched. Note that the array *must* be sorted.
count - The number of elements in the array
size - The size of one element
comparefunction - The function which is called when two elements
must be compared. The function gets the addresses of two
elements of the array and must return 0 is both are equal,
< 0 if the first element is less than the second and > 0
otherwise.
A pointer to the element which equals key in the array or NULL if
no such element could be found.
void bzero(
void * ptr,
size_t len)
Write len zero bytes to ptr. If len is zero, does nothing.
ptr - The first byte of the area in memory to be cleared.
len - How many bytes to clear.
void * calloc(
size_t count,
size_t size)
Allocate size bytes of memory, clears the memory (sets all bytes to
0) and returns the address of the first byte.
count - How many time size
size - How much memory to allocate.
A pointer to the allocated memory or NULL. If you don't need the
memory anymore, you can pass this pointer to free(). If you don't,
the memory will be freed for you when the application exits.
This function must not be used in a shared library or
in a threaded application.
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 apropriately.
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 behaviour, 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 th 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 - path to the file
mode - permission bits
Permission bits of the file given by path are changed accordingly
to given mode.
int chown(
const char *path,
uid_t owner,
gid_t group)
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.
clock() returns an approximation of the time passed since
the program was started
The time passed in CLOCKS_PER_SEC units. To get the
number of seconds divide by CLOCKS_PER_SEC.
This function must not be used in a shared library or
in a threaded application.
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 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.
char * ctime(
const time_t * tt)
The ctime() function converts the broken-down time value tt
into a string.
See ctime_r() for details.
A statically allocated buffer with the converted time. Note that
the contents of the buffer might get lost with the call of any of the
date and time functions.
time_t tt;
char * str;
// Get time
time (&tt);
// Convert to string
str = ctime (&tt);
This function must not be used in a shared library or
in a threaded application. Use ctime_r() instead.
char * ctime_r(
const time_t * tt,
char * buf)
The ctime_r() function converts the time value tt into a string with
this format:
"Wed Jun 30 21:49:08 1993\n"
tt - Convert this time.
buf - Buffer of at least 26 characters to store the string in
The pointer passed in buf, containing the converted time. Note that
there is a newline at the end of the buffer.
time_t tt;
char str[26];
// Get time
time (&tt);
// Convert to string
ctime (&tt, str);
double difftime(
time_t time2,
time_t time1)
difftime() returns the number of seconds elapsed between
time time2 and time time1.
time2 - time value from which time1 is subtracted
time1 - time value that is subtracted from time2
The number of seconds elapsed in double precision.
time_t tt1, tt2;
double secs;
time (&tt1);
...
time (&tt2);
secs = difftime(tt2, tt1);
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.
div_t div(
int numer,
int denom)
Compute quotient en remainder of two int variables
numer = the numerator
denom = the denominator
a struct with two ints quot and rem with
quot = numer / denom and rem = numer % denom.
typedef struct div_t {
int quot;
int rem;
} div_t;
NOTES
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 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
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, ...)
int execlp(
const char *file,
const char *arg, ...)
int execv(
const char *path,
char *const argv[])
Executes a file with specified arguments.
file - Name of the file to execute.
argv - Array of arguments given to main() function of the executed
file.
0 in case of success. In case of failure errno is set appropriately
and function returns -1.
See execve documentation.
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 specified arguments.
file - Name of the file to execute.
argv - Array of arguments given to main() function of the executed
file.
0 in case of success. In case of failure errno is set appropriately
and function returns -1.
See execve documentation.
Terminates the running program. The code is returned to the
program which has called the running program.
code - Exit code. 0 for success, other values for failure.
None. This function does not return.
This function must not be used in a shared library or
in a threaded application.
- EXAMPLE
- if (no_problems)
- exit (0);
- if (warning)
- exit (5);
- if (error)
- exit (10);
- if (fatal)
- exit (20);
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 apropriately.
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 behaviour, use dos.library/CurrentDir() instead.
int fchmod(
int filedes,
mode_t mode)
int fchown(
int fd,
uid_t owner,
gid_t group)
int 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.
This function must not be used in a shared library or
in a threaded application.
int fcntl(
int fd,
int cmd,
...)
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 com
patible with the mode of the file descriptor. The file
position indicator of the new stream is set to that
belonging to filedes, and the error and end-of-file indica
tors are cleared. Modes "w" or "w+" do not cause trunca
tion of the file. The file descriptor is not dup'ed, 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.
This function must not be used in a shared library or
in a threaded application.
Test the EOF-Flag of a stream. This flag is set automatically by
any function which recognises 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 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 fflush(
FILE * stream)
Flush a stream. If the stream is an input stream, then the stream
is synchronised 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 fgetc(
FILE * stream)
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 fgetpos(
FILE * stream,
fpos_t * pos)
Get the current position in a stream. This function is eqivalent
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 * 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
}
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)
FILE * 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.
This function must not be used in a shared library or
in a threaded application.
Most modes are not supported right now.
int 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 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 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 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.
void free(
void * memory)
Return memory allocated with malloc() or a similar function to the
system.
memory - The result of the previous call to malloc(), etc. or
NULL.
This function must not be used in a shared library or in a threaded
application.
FILE *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 com
patible with the mode of the file descriptor. The file
position indicator of the new stream is set to that
belonging to fildes, and the error and end-of-file indica
tors are cleared. Modes "w" or "w+" do not cause trunca
tion of the file. The file descriptor is not dup'ed, and
will be closed when the stream created by fdopen is
closed.
stream - the stream to wich the file will be associated.
int 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 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
int fsetpos(
FILE * stream,
const fpos_t * pos)
Change the current position in a stream. This function is eqivalent
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 fstat(
int fd,
struct stat *sb)
long 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.
int ftime(
struct timeb *tb)
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.
size_t 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.
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 significan 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.
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.
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 *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.
char *getenv(
const char *name)
Get an environment variable.
name - Name of the environment variable.
Pointer to the variable's value, or NULL on failure.
This function must not be used in a shared library.
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
|
