|
www.riscos.com Technical Support: |
The shared C library is a relocatable module in the RISC OS ROM. Applications which are resident in memory at the same time can share it. It provides all the standard facilities of the language, as defined by the ANSI standard document. Code using calls to the shared C library will be portable to other environments if an ANSI compiler and library are available for that environment.
C and C++ programs are linked with a small piece of code and data called Stubs, which itself interfaces with the shared C library. The stubs contain your program's copy of the library's data, and an entry vector which allows your program to locate library routines in the C library module. Stubs is found in the directory AcornC_C++.Libraries.clib.o.
Use of the shared C library:
(For example, the Dhrystone benchmark runs just as quickly using the shared C library as when linked stand-alone with ANSILib.)
Without the shared C library, it would not be possible to pack so much into Acorn C/C++.
The assert macro puts diagnostics into programs. When it is executed, if its argument expression is false, it writes information about the call that failed (including the text of the argument, the name of the source file, and the source line number, the last two of these being, respectively, the values of the preprocessing macros __FILE__ and __LINE__) on the standard error stream. It then calls the abort function. If its argument expression is true, the assert macro returns no value.
If NDEBUG is #defined prior to inclusion of assert.h, calls to assert expand to null statements. This provides a simple way to turn off the generation of diagnostics selectively.
Note that assert.h may be included more than once in a program with different settings of NDEBUG.
ctype.h declares several functions useful for testing and mapping characters. In all cases the argument is an int, the value of which is representable as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, the behaviour is undefined.
This file contains the definition of the macro errno, which is of type volatile int. It contains three macro constants defining the error conditions listed below.
A range error occurs if the result of a function cannot be represented as a double value. If the result overflows (the magnitude of the result is so large that it cannot be represented in an object of the specified type), the function returns the value of the macro HUGE_VAL, with the same sign as the correct value of the function; the integer expression errno acquires the value of the macro ERANGE. If the result underflows (the magnitude of the result is so small that it cannot be represented in an object of the specified type), the function returns zero; the integer expression errno acquires the value of the macro ERANGE. ERANGE may be used by non-mathematical functions.
This file contains a set of macro constants which define the limits of computation on floating point numbers. These are discussed in the C implementation details.
This set of macro constants determines the upper and lower value limits for integral objects of various types, as follows:
| Object type | Minimum value | Maximum value |
|---|---|---|
| Byte (number of bits) | 0 | 8 |
| Signed char | -128 | 127 |
| Unsigned char | 0 | 255 |
| Char | 0 | 255 |
| Multibyte character (number of bytes) | 0 | 1 |
| Short int | -0x8000 | 0x7fff |
| Unsigned short int | 0 | 65535 |
| Int | (~0x7fffffff) | 0x7fffffff |
| Unsigned int | 0 | 0xffffffff |
| Long int | (~0x7fffffff) | 0x7fffffff |
| Unsigned long int | 0 | 0xffffffff |
See also the C implementation details.
This file handles national characteristics, such as the different orderings month-day-year (USA) and day-month-year (UK).
char *setlocale(int category, const char *locale)
Selects the appropriate part of the program's locale as specified by the category and locale arguments. The setlocale function may be used to change or query the program's entire current locale or portions thereof. Locale information is divided into the following types:
| LC_COLLATE | string collation |
| LC_CTYPE | character type |
| LC_MONETARY | monetary formatting |
| LC_NUMERIC | numeric string formatting |
| LC_TIME | time formatting |
| LC_ALL | entire locale |
The locale string specifies which locale set of information is to be used. For example,
setlocale(LC_MONETARY,"uk")
would insert monetary information into the lconv structure. To query the current locale information, set the locale string to null and read the string returned.
struct lconv *localeconv(void)
Sets the components of an object with type struct lconv with values appropriate for the formatting of numeric quantities (monetary and otherwise) according to the rules of the current locale. The members of the structure with type char * are strings, any of which (except decimal_point) can point to "", to indicate that the value is not available in the current locale or is of zero length. The members with type char are non-negative numbers, any of which can be CHAR_MAX to indicate that the value is not available in the current locale. The members included are described above.
localeconv returns a pointer to the filled in object. The structure pointed to by the return value will not be modified by the program, but may be overwritten by a subsequent call to the localeconv function. In addition, calls to the setlocale function with categories LC_ALL, LC_MONETARY, or LC_NUMERIC may overwrite the contents of the structure.
This file contains the prototypes for 22 mathematical functions. All return the type double.
| Function | Returns |
|---|---|
| double acos(double x) | arc cosine of x. A domain error occurs for arguments not in the range -1 to 1 |
| double asin(double x) | arc sine of x. A domain error occurs for arguments not in the range -1 to 1 |
| double atan(double x) | arc tangent of x |
| double atan2(double x, double y) | arc tangent of y/x |
| double cos(double x) | cosine of x (measured in radians) |
| double sin(double x) | sine of x (measured in radians) |
| double tan(double x) | tangent of x (measured in radians) |
| double cosh(double x) | hyperbolic cosine of x |
| double sinh(double x) | hyperbolic sine of x |
| double tanh(double x) | hyperbolic tangent of x |
| double exp(double x) | exponential function of x |
| double frexp(double x, int *exp) | the value x, such that x is a double with magnitude in the interval 0.5 to 1.0 or zero, and value equals x times 2 raised to the power *exp |
| double ldexp(double x, int exp) | x times 2 raised to the power of exp |
| double log(double x) | natural logarithm of x |
| double log10(double x) | log to the base 10 of x |
| double modf(double x, double *iptr) | signed fractional part of x. Stores integer part of x in object pointed to by iptr. |
| double pow(double x, double y) | x raised to the power of y |
| double sqrt(double x) | positive square root of x |
| double ceil(double x) | smallest integer not less than x (ie rounding up) |
| double fabs(double x) | absolute value of x |
| double floor(double x) | largest integer not greater than x (ie rounding down) |
| double fmod(double x, double y) | floating-point remainder of x/y |
This file declares two functions, and one type, for bypassing the normal function call and return discipline (useful for dealing with unusual conditions encountered in a low-level function of a program). It also defines the jmp_buf structure type required by these routines.
int setjmp(jmp_buf env)
The calling environment is saved in env, for later use by the longjmp function. If the return is from a direct invocation, the setjmp function returns the value zero. If the return is from a call to the longjmp function, the setjmp function returns a non-zero value.
void longjmp(jmp_buf env, int val)
The environment saved in env by the most recent call to setjmp is restored. If there has been no such call, or if the function containing the call to setjmp has terminated execution (eg with a return statement) in the interim, the behaviour is undefined. All accessible objects have values as at the time longjmp was called, except that the values of objects of automatic storage duration that do not have volatile type and that have been changed between the setjmp and longjmp calls are indeterminate.
As it bypasses the usual function call and return mechanism, the longjmp function executes correctly in contexts of interrupts, signals and any of their associated functions. However, if the longjmp function is invoked from a nested signal handler (that is, from a function invoked as a result of a signal raised during the handling of another signal), the behaviour is undefined.
After longjmp is completed, program execution continues as if the corresponding call to setjmp had just returned the value specified by val. The longjmp function cannot cause setjmp to return the value 0; if val is 0, setjmp returns the value 1.
Signal declares a type (sig_atomic_t) and two functions.
It also defines several macros for handling various signals (conditions that may be reported during program execution). These are SIG_DFL (default routine), SIG_IGN (ignore signal routine) and SIG_ERR (dummy routine used to flag error return from signal).
void (*signal (int sig, void (*func)(int)))(int)
Think of this as
typedef void Handler(int); Handler *signal(int, Handler *);
Chooses one of three ways in which receipt of the signal number sig is to be subsequently handled. If the value of func is SIG_DFL, default handling for that signal will occur. If the value of func is SIG_IGN, the signal will be ignored. Otherwise func points to a function to be called when that signal occurs.
When a signal occurs, if func points to a function, first the equivalent of signal(sig, SIG_DFL) is executed. (If the value of sig is SIGILL, whether the reset to SIG_DFL occurs is implementation-defined (under RISC OS the reset does occur)). Next, the equivalent of (*func)(sig); is executed. The function may terminate by calling the abort, exit or longjmp function. If func executes a return statement and the value of sig was SIGFPE or any other implementation-defined value corresponding to a computational exception, the behaviour is undefined. Otherwise, the program will resume execution at the point it was interrupted.
If the signal occurs other than as a result of calling the abort or raise function, the behaviour is undefined if the signal handler calls any function in the standard library other than the signal function itself or refers to any object with static storage duration other than by assigning a value to a volatile static variable of type sig_atomic_t. At program start-up, the equivalent of signal(sig, SIG_IGN) may be executed for some signals selected in an implementation-defined manner (under RISC OS this does not occur); the equivalent of signal(sig, SIG_DFL) is executed for all other signals defined by the implementation.
If the request can be honoured, the signal function returns the value of func for most recent call to signal for the specified signal sig. Otherwise, a value of SIG_ERR is returned and the integer expression errno is set to indicate the error.
This file declares a type and defines three macros, for advancing through a list of arguments whose number and types are not known to the called function when it is translated. A function may be called with a variable number of arguments of differing types. Its parameter list contains one or more parameters, the rightmost of which plays a special role in the access mechanism, and will be called parmN in this description.
char *va_list[1]
An array type suitable for holding information needed by the macro va_arg and the function va_end. The called function declares a variable (referred to as ap) having type va_list. The variable ap may be passed as an argument to another function. va_list is an array type so that when an object of that type is passed as an argument it gets passed by reference, but this is not required by the ANSI specification and cannot be relied on.
The va_start macro will be executed before any access to the unnamed arguments. The parameter ap points to an object that has type va_list. The va_start macro initialises ap for subsequent use by va_arg and va_end. The parameter parmN is the identifier of the rightmost parameter in the variable parameter list in the function definition (the one just before the , ...). If the parameter parmN is declared with the register storage class the behaviour is undefined.
Returns: no value.
The va_arg macro expands to an expression that has the type and value of the next argument in the call. The parameter ap is the same as the va_list ap initialised by va_start. Each invocation of va_arg modifies ap so that successive arguments are returned in turn. The parameter type is a type name such that the type of a pointer to an object that has the specified type can be obtained simply by postfixing a * to type. If type disagrees with the type of the actual next argument (as promoted according to the default argument promotions), the behaviour is undefined.
Returns: The first invocation of the va_arg macro after that of the va_start macro returns the value of the argument after that specified by parmN. Successive invocations return the values of the remaining arguments in succession. Care is taken in va_arg so that illegal things like va_arg(ap,char) - which may seem natural but are in fact illegal - are caught. va_arg(ap,float) is wrong but cannot be patched up at the C macro level.
#define va_end(ap) ((void)(*(ap) = (char *)-256))
The va_end macro facilitates a normal return from the function whose variable argument list was referenced by the expansion of va_start that initialised the va_list ap. If the va_end macro is not invoked before the return, the behaviour is undefined.
This file contains a macro for calculating the offset of fields within a structure. It also defines the pointer constant NULL and three types.
stdio declares two types, several macros, and many functions for performing input and output. For a discussion on Streams and Files refer to sections 4.9.2 and 4.9.3 in the ANSI standard or to one of the other references given in the Introduction to this Guide.
int remove(const char * filename)
Causes the file whose name is the string pointed to by filename to be removed. Subsequent attempts to open the file will fail, unless it is created anew. If the file is open, the behaviour of the remove function is implementation-defined (under RISC OS the operation fails).
Returns: zero if the operation succeeds, non-zero if it fails.
int rename(const char * old, const char * new)
Causes the file whose name is the string pointed to by old to be henceforth known by the name given by the string pointed to by new. The file named old is effectively removed. If a file named by the string pointed to by new exists prior to the call of the rename function, the behaviour is implementation-defined (under RISC OS, the operation fails).
Returns: zero if the operation succeeds, non-zero if it fails, in which case if the file existed previously it is still known by its original name.
FILE *tmpfile(void)
Creates a temporary binary file that will be automatically removed when it is closed or at program termination. The file is created if possible in Wimp$ScrapDir, or failing that, in the directory $.tmp; it is then opened for update.
Returns: a pointer to the stream of the file that it created. If the file cannot be created, a null pointer is returned.
char *tmpnam(char * s)
Generates a string that is not the same as the name of an existing file. The tmpnam function generates a different string each time it is called, up to TMP_MAX times. If it is called more than TMP_MAX times, the behaviour is implementation-defined (under RISC OS the algorithm for the name generation works just as well after tmpnam has been called more than TMP_MAX times as before; a name clash is impossible in any single half year period).
Returns: If the argument is a null pointer, the tmpnam function leaves its result in an internal static object and returns a pointer to that object. Subsequent calls to the tmpnam function may modify the same object. If the argument is not a null pointer, it is assumed to point to an array of at least L_tmpnam characters; the tmpnam function writes its result in that array and returns the argument as its value.
int fclose(FILE * stream)
Causes the stream pointed to by stream to be flushed and the associated file to be closed. Any unwritten buffered data for the stream are delivered to the host environment to be written to the file; any unread buffered data are discarded. The stream is disassociated from the file. If the associated buffer was automatically allocated, it is deallocated.
Returns: zero if the stream was successfully closed, or EOF if any errors were detected or if the stream was already closed.
int fflush(FILE * stream)
If the stream points to an output or update stream in which the most recent operation was output, the fflush function causes any unwritten data for that stream to be delivered to the host environment to be written to the file. If the stream points to an input or update stream, the fflush function undoes the effect of any preceding ungetc operation on the stream.
Returns: EOF if a write error occurs.
FILE *fopen(const char * filename, const char * mode)
Opens the file whose name is the string pointed to by filename, and associates a stream with it. The argument mode points to a string beginning with one of the following sequences:
| r | open text file for reading |
| w | create text file for writing, or truncate to zero length |
| a | append; open text file or create for writing at eof |
| rb | open binary file for reading |
| wb | create binary file for writing, or truncate to zero length |
| ab | append; open binary file or create for writing at eof |
| r+ | open text file for update (reading and writing) |
| w+ | create text file for update, or truncate to zero length |
| a+ | append; open text file or create for update, writing at eof |
| r+b or rb+ | open binary file for update (reading and writing) |
| w+b or wb+ | create binary file for update, or truncate to zero length |
| a+b or ab+ | append; open binary file or create for update, writing at eof |
Returns: a pointer to the object controlling the stream. If the open operation fails, fopen returns a null pointer.
0x7E (tilde) inclusive).
FILE *freopen(const char * filename, const char * mode,
FILE * stream)
Opens the file whose name is the string pointed to by filename and associates the stream pointed to by stream with it. The mode argument is used just as in the fopen function. The freopen function first attempts to close any file that is associated with the specified stream. Failure to close the file successfully is ignored. The error and end-of-file indicators for the stream are cleared.
Returns: a null pointer if the operation fails. Otherwise, freopen returns the value of the stream.
int setvbuf(FILE * stream, char * buf, int mode, size_t
size)
This may be used after the stream pointed to by stream has been associated with an open file but before it is read or written. The argument mode determines how stream will be buffered, as follows:
If buf is not the null pointer, the array it points to may be used instead of an automatically allocated buffer (the buffer must have a lifetime at least as great as the open stream, so the stream should be closed before a buffer that has automatic storage duration is deallocated upon block exit). The argument size specifies the size of the array. The contents of the array at any time are indeterminate. buf must be non-null.
Returns: zero on success, or non-zero if an invalid value is given for mode or size, or if the request cannot be honoured.
int fprintf(FILE * stream, const char * format, ...)
writes output to the stream pointed to by stream, under control of the string pointed to by format that specifies how subsequent arguments are converted for output. If there are insufficient arguments for the format, the behaviour is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated but otherwise ignored. The fprintf function returns when the end of the format string is reached. The format must be a multibyte character sequence, beginning and ending in its initial shift state (in all locales supported under RISC OS this is the same as a plain character string). The format is composed of zero or more directives: ordinary multibyte characters (not %), which are copied unchanged to the output stream; and conversion specifiers, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the character %. For a complete description of the available conversion specifiers refer to section 4.9.6.1 in the ANSI standard or to one of the other references in the Introduction to this Guide. The minimum value for the maximum number of characters that can be produced by any single conversion is at least 509.
A brief and incomplete description of conversion specifications is:
[flags][field width][.precision]specifier-char
flags is most commonly -, indicating left justification of the output item within the field. If omitted, the item will be right justified.
field width is the minimum width of field to use. If the formatted item is longer, a bigger field will be used; otherwise, the item will be right (left) justified in the field.
precision is the minimum number of digits to print for a d, i, o, u, x or X conversion, the number of digits to appear after the decimal digit 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 written from strings in an s conversion.
Either or both of field width and precision may be *, indicating that the value is an argument to printf.
The specifier chars are:
| d, i | int printed as signed decimal |
| o, u, x, X | unsigned int value printed as unsigned octal, decimal or hexadecimal |
| f | double value printed in the style [-]ddd.ddd |
| e, E | double value printed in the style [-]d.ddd...e±dd |
| g, G | double printed in f or e format, whichever is more appropriate |
| c | int value printed as unsigned char |
| s | char * value printed as a string of characters |
| p | void * argument printed as a hexadecimal address |
| % | write a literal % |
Returns: the number of characters transmitted, or a negative value if an output error occurred.
int printf(const char * format, ...)
Equivalent to fprintf with the argument stdout interposed before the arguments to printf.
Returns: the number of characters transmitted, or a negative value if an output error occurred.
int sprintf(char * s, const char * format, ...)
Equivalent to fprintf, except that the argument s specifies an array into which the generated output is to be written, rather than to a stream. A null character is written at the end of the characters written; it is not counted as part of the returned sum.
Returns: the number of characters written to the array, not counting the terminating null character.
int fscanf(FILE * stream, const char * format, ...)
Reads input from the stream pointed to by stream, under control of the string pointed to by format that specifies the admissible input sequences and how they are to be converted for assignment, using subsequent arguments as pointers to the objects to receive the converted input. If there are insufficient arguments for the format, the behaviour is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated but otherwise ignored. The format is composed of zero or more directives, one or more white-space characters, an ordinary character (not %), or a conversion specification. Each conversion specification is introduced by the character %. For a description of the available conversion specifiers refer to section 4.9.6.2 in the ANSI standard, or to any of the references listed in the Introduction. A brief list is given above, under the entry for fprintf.
If end-of-file is encountered during input, conversion is terminated. If end-of-file occurs before any characters matching the current directive have been read (other than leading white space, where permitted), execution of the current directive terminates with an input failure; otherwise, unless execution of the current directive is terminated with a matching failure, execution of the following directive (if any) is terminated with an input failure.
If conversions terminate on a conflicting input character, the offending input character is left unread in the input stream. Trailing white space (including newline characters) is left unread unless matched by a directive. The success of literal matches and suppressed assignments is not directly determinable other than via the %n directive.
Returns: the value of the macro EOF if an input failure occurs before any conversion. Otherwise, the fscanf function returns the number of input items assigned, which can be fewer than provided for, or even zero, in the event of an early conflict between an input character and the format.
int scanf(const char * format, ...)
Equivalent to fscanf with the argument stdin interposed before the arguments to scanf.
Returns: the value of the macro EOF if an input failure occurs before any conversion. Otherwise, the scanf function returns the number of input items assigned, which can be fewer than provided for, or even zero, in the event of an early matching failure.
int sscanf(const char * s, const char * format, ...)
Equivalent to fscanf except that the argument s specifies a string from which the input is to be obtained, rather than from a stream. Reaching the end of the string is equivalent to encountering end-of-file for the fscanf function.
Returns: the value of the macro EOF if an input failure occurs before any conversion. Otherwise, the scanf function returns the number of input items assigned, which can be fewer than provided for, or even zero, in the event of an early matching failure.
int vprintf(const char * format, va_list arg)
Equivalent to printf, with the variable argument list replaced by arg, which has been initialised by the va_start macro (and possibly subsequent va_arg calls). The vprintf function does not invoke the va_end function.
Returns: the number of characters transmitted, or a negative value if an output error occurred.
int vfprintf(FILE * stream,const char * format, va_list
arg)
Equivalent to fprintf, with the variable argument list replaced by arg, which has been initialised by the va_start macro (and possibly subsequent va_arg calls). The vfprintf function does not invoke the va_end function.
Returns: the number of characters transmitted, or a negative value if an output error occurred.
int vsprintf(char * s, const char * format, va_list arg)
Equivalent to sprintf, with the variable argument list replaced by arg, which has been initialised by the va_start macro (and possibly subsequent va_arg calls). The vsprintf function does not invoke the va_end function.
Returns: the number of characters written in the array, not counting the terminating null character.
int fgetc(FILE * stream)
Obtains the next character (if present) as an unsigned char converted to an int, from the input stream pointed to by stream, and advances the associated file position indicator (if defined).
Returns: the next character from the input stream pointed to by stream. If the stream is at end-of-file, the end-of-file indicator is set and fgetc returns EOF. If a read error occurs, the error indicator is set and fgetc returns EOF.
char *fgets(char * s, int n, FILE * stream)
Reads at most one less than the number of characters specified by n from the stream pointed to by stream into the array pointed to by s. No additional characters are read after a newline character (which is retained) or after end-of-file. A null character is written immediately after the last character read into the array.
Returns: s if successful. If end-of-file is encountered and no characters have been read into the array, the contents of the array remain unchanged and a null pointer is returned. If a read error occurs during the operation, the array contents are indeterminate and a null pointer is returned.
int fputc(int c, FILE * stream)
Writes the character specified by c (converted to an unsigned char) to the output stream pointed to by stream, at the position indicated by the associated file position indicator (if defined), and advances the indicator appropriately. If the file cannot support positioning requests, or if the stream was opened with append mode, the character is appended to the output stream.
Returns: the character written. If a write error occurs, the error indicator is set and fputc returns EOF.
int getc(FILE * stream)
Equivalent to fgetc except that it may be (and is under RISC OS) implemented as a macro. stream may be evaluated more than once, so the argument should never be an expression with side effects.
Returns: the next character from the input stream pointed to by stream. If the stream is at end-of-file, the end-of-file indicator is set and getc returns EOF. If a read error occurs, the error indicator is set and getc returns EOF.
int getchar(void)
Equivalent to getc with the argument stdin.
Returns: the next character from the input stream pointed to by stdin. If the stream is at end-of-file, the end-of-file indicator is set and getchar returns EOF. If a read error occurs, the error indicator is set and getchar returns EOF.
char *gets(char * s)
Reads characters from the input stream pointed to by stdin into the array pointed to by s, until end-of-file is encountered or a newline character is read. Any newline character is discarded, and a null character is written immediately after the last character read into the array.
Returns: s if successful. If end-of-file is encountered and no characters have been read into the array, the contents of the array remain unchanged and a null pointer is returned. If a read error occurs during the operation, the array contents are indeterminate and a null pointer is returned.
int putc(int c, FILE * stream)
Equivalent to fputc except that it may be (and is under RISC OS) implemented as a macro. stream may be evaluated more than once, so the argument should never be an expression with side effects.
Returns: the character written. If a write error occurs, the error indicator is set and putc returns EOF.
int putchar(int c)
Equivalent to putc with the second argument stdout.
Returns: the character written. If a write error occurs, the error indicator is set and putc returns EOF.
int ungetc(int c, FILE * stream)
Pushes the character specified by c (converted to an unsigned char) back onto the input stream pointed to by stream. The character will be returned by the next read on that stream. An intervening call to the fflush function or to a file positioning function (fseek, fsetpos, rewind) discards any pushed-back characters. The external storage corresponding to the stream is unchanged. One character pushback is guaranteed. If the unget function is called too many times on the same stream without an intervening read or file positioning operation on that stream, the operation may fail. If the value of c equals that of the macro EOF, the operation fails and the input stream is unchanged.
A successful call to the ungetc function clears the end-of-file indicator. The value of the file position indicator after reading or discarding all pushed-back characters will be the same as it was before the characters were pushed back. For a text stream, the value of the file position indicator after a successful call to the ungetc function is unspecified until all pushed-back characters are read or discarded. For a binary stream, the file position indicator is decremented by each successful call to the ungetc function; if its value was zero before a call, it is indeterminate after the call.
Returns: the character pushed back after conversion, or EOF if the operation fails.
size_t fread(void * ptr,size_t size,
size_t nmemb, FILE * stream)
Reads into the array pointed to by ptr, up to nmemb members whose size is specified by size, from the stream pointed to by stream. The file position indicator (if defined) is advanced by the number of characters successfully read. If an error occurs, the resulting value of the file position indicator is indeterminate. If a partial member is read, its value is indeterminate. The ferror or feof function shall be used to distinguish between a read error and end-of-file.
Returns: the number of members successfully read, which may be less than nmemb if a read error or end-of-file is encountered. If size or nmemb is zero, fread returns zero and the contents of the array and the state of the stream remain unchanged.
size_t fwrite(const void * ptr,
size_t size, size_t nmemb, FILE * stream)
Writes, from the array pointed to by ptr up to nmemb members whose size is specified by size, to the stream pointed to by stream. The file position indicator (if defined) is advanced by the number of characters successfully written. If an error occurs, the resulting value of the file position indicator is indeterminate.
Returns: the number of members successfully written, which will be less than nmemb only if a write error is encountered.
int fgetpos(FILE * stream, fpos_t * pos)
Stores the current value of the file position indicator for the stream pointed to by stream in the object pointed to by pos. The value stored contains unspecified information usable by the fsetpos function for repositioning the stream to its position at the time of the call to the fgetpos function.
Returns: zero, if successful. Otherwise non-zero is returned and the integer expression errno is set to an implementation-defined non-zero value (under RISC OS fgetpos cannot fail).
int fseek(FILE * stream, long int offset, int whence)
Sets the file position indicator for the stream pointed to by stream. For a binary stream, the new position is at the signed number of characters specified by offset away from the point specified by whence. The specified point is the beginning of the file for SEEK_SET, the current position in the file for SEEK_CUR, or end-of-file for SEEK_END. A binary stream need not meaningfully support fseek calls with a whence value of SEEK_END, though the Acorn implementation does. For a text stream, offset is either zero or a value returned by an earlier call to the ftell function on the same stream; whence is then SEEK_SET. The Acorn implementation also allows a text stream to be positioned in exactly the same manner as a binary stream, but this is not portable. The fseek function clears the end-of-file indicator and undoes any effects of the ungetc function on the same stream. After an fseek call, the next operation on an update stream may be either input or output.
Returns: non-zero only for a request that cannot be satisfied.
int fsetpos(FILE * stream, const fpos_t * pos)
Sets the file position indicator for the stream pointed to by stream according to the value of the object pointed to by pos, which is a value returned by an earlier call to the fgetpos function on the same stream. The fsetpos function clears the end-of-file indicator and undoes any effects of the ungetc function on the same stream. After an fsetpos call, the next operation on an update stream may be either input or output.
Returns: zero, if successful. Otherwise non-zero is returned and the integer expression errno is set to an implementation-defined non-zero value (under RISC OS the value is that of EDOM in math.h).
long int ftell(FILE * stream)
Obtains the current value of the file position indicator for the stream pointed to by stream. For a binary stream, the value is the number of characters from the beginning of the file. For a text stream, the file position indicator contains unspecified information, usable by the fseek function for returning the file position indicator to its position at the time of the ftell call; the difference between two such return values is not necessarily a meaningful measure of the number of characters written or read. However, for the Acorn implementation, the value returned is merely the byte offset into the file, whether the stream is text or binary.
Returns: if successful, the current value of the file position indicator. On failure, the ftell function returns -1L and sets the integer expression errno to an implementation-defined non-zero value (under RISC OS ftell cannot fail).
void rewind(FILE * stream)
Sets the file position indicator for the stream pointed to by stream to the beginning of the file. It is equivalent to (void)fseek(stream, 0L, SEEK_SET) except that the error indicator for the stream is also cleared.
Returns: no value.
void clearerr(FILE * stream)
Clears the end-of-file and error indicators for the stream pointed to by stream. These indicators are cleared only when the file is opened or by an explicit call to the clearerr function or to the rewind function.
Returns: no value.
int feof(FILE * stream)
Tests the end-of-file indicator for the stream pointed to by stream.
Returns: non-zero if the end-of-file indicator is set for stream.
void perror(const char * s)
Maps the error number in the integer expression errno to an error message. It writes a sequence of characters to the standard error stream thus: first (if s is not a null pointer and the character pointed to by s is not the null character), the string pointed to by s followed by a colon and a space; then an appropriate error message string followed by a newline character. The contents of the error message strings are the same as those returned by the strerror function with argument errno, which are implementation-defined.
stdlib.h declares four types, several general purpose functions, and defines several macros.
int atoi(const char * nptr)
Converts the initial part of the string pointed to by nptr to int representation.
Returns: the converted value.
long int atol(const char * nptr)
Converts the initial part of the string pointed to by nptr to long int representation.
Returns: the converted value.
double strtod(const char * nptr, char ** endptr)
Converts the initial part of the string pointed to by nptr to double representation. First it decomposes the input string into three parts: an initial, possibly empty, sequence of white-space characters (as specified by the isspace function), a subject sequence resembling a floating point constant, and a final string of one or more unrecognised characters, including the terminating null character of the input string. It then attempts to convert the subject sequence to a floating point number, and returns the result. A pointer to the final string is stored in the object pointed to by endptr, provided that endptr is not a null pointer.
Returns: the converted value if any. If no conversion could be performed, zero is returned. If the correct value is outside the range of representable values, plus or minus HUGE_VAL is returned (according to the sign of the value), and the value of the macro ERANGE is stored in errno. If the correct value would cause underflow, zero is returned and the value of the macro ERANGE is stored in errno.
long int strtol(const char * nptr, char **endptr, int
base)
Converts the initial part of the string pointed to by nptr to long int representation. First it decomposes the input string into three parts: an initial, possibly empty, sequence of white-space characters (as specified by the isspace function), a subject sequence resembling an integer represented in some radix determined by the value of base, and a final string of one or more unrecognised characters, including the terminating null character of the input string.
It then attempts to convert the subject sequence to an integer, and returns the result. If the value of base is 0, the expected form of the subject sequence is that of an integer constant (described precisely in the ANSI standard, section 3.1.3.2), optionally preceded by a + or - sign, but not including an integer suffix. If the value of base is between 2 and 36, the expected form of the subject sequence is a sequence of letters and digits representing an integer with the radix specified by base, optionally preceded by a plus or minus sign, but not including an integer suffix. The letters from a (or A) through z (or Z) are ascribed the values 10 to 35; only letters whose ascribed values are less than that of the base are permitted. If the value of base is 16, the characters 0x or 0X may optionally precede the sequence of letters and digits following the sign if present. A pointer to the final string is stored in the object pointed to by endptr, provided that endptr is not a null pointer.
Returns: the converted value if any. If no conversion could be performed, zero is returned. If the correct value is outside the range of representable values, LONG_MAX or LONG_MIN is returned (according to the sign of the value), and the value of the macro ERANGE is stored in errno.
unsigned long int strtoul(const char * nptr, char **
endptr, int base)
Converts the initial part of the string pointed to by nptr to unsigned long int representation. First it decomposes the input string into three parts: an initial, possibly empty, sequence of white space characters (as determined by the isspace function), a subject sequence resembling an unsigned integer represented in some radix determined by the value of base, and a final string of one or more unrecognised characters, including the terminating null character of the input string.
It then attempts to convert the subject sequence to an unsigned integer, and returns the result. If the value of base is zero, the expected form of the subject sequence is that of an integer constant (described precisely in the ANSI Draft, section 3.1.3.2), optionally preceded by a + or - sign, but not including an integer suffix. If the value of base is between 2 and 36, the expected form of the subject sequence is a sequence of letters and digits representing an integer with the radix specified by base, optionally preceded by a + or - sign, but not including an integer suffix. The letters from a (or A) through z (or Z) stand for the values 10 to 35; only letters whose ascribed values are less than that of the base are permitted. If the value of base is 16, the characters 0x or 0X may optionally precede the sequence of letters and digits following the sign, if present. A pointer to the final string is stored in the object pointed to by endptr, provided that endptr is not a null pointer.
Returns: the converted value if any. If no conversion could be performed, zero is returned. If the correct value is outside the range of representable values, ULONG_MAX is returned, and the value of the * macro ERANGE is stored in errno.
void srand(unsigned int seed)
Uses its argument as a seed for a new sequence of pseudo-random numbers to be returned by subsequent calls to rand. If srand is then called with the same seed value, the sequence of pseudo-random numbers will be repeated. If rand is called before any calls to srand have been made, the same sequence is generated as when srand is first called with a seed value of 1.
void free(void * ptr)
Causes the space pointed to by ptr to be deallocated (made available for further allocation). If ptr is a null pointer, no action occurs. Otherwise, if ptr does not match a pointer earlier returned by calloc, malloc or realloc or if the space has been deallocated by a call to free or realloc, the behaviour is undefined.
void *malloc(size_t size)
Allocates space for an object whose size is specified by size and whose value is indeterminate.
Returns: either a null pointer or a pointer to the allocated space.
void *realloc(void * ptr, size_t size)
Changes the size of the object pointed to by ptr to the size specified by size. The contents of the object is unchanged up to the lesser of the new and old sizes. If the new size is larger, the value of the newly allocated portion of the object is indeterminate. If ptr is a null pointer, the realloc function behaves like a call to malloc for the specified size. Otherwise, if ptr does not match a pointer earlier returned by calloc, malloc or realloc, or if the space has been deallocated by a call to free or realloc, the behaviour is undefined. If the space cannot be allocated, the object pointed to by ptr is unchanged. If size is zero and ptr is not a null pointer, the object it points to is freed.
Returns: either a null pointer or a pointer to the possibly moved allocated space.
void abort(void)
Causes abnormal program termination to occur, unless the signal SIGABRT is being caught and the signal handler does not return. Whether open output streams are flushed or open streams are closed or temporary files removed is implementation-defined (under RISC OS all these occur). An implementation-defined form of the status 'unsuccessful termination' (1 under RISC OS) is returned to the host environment by means of a call to raise(SIGABRT).
int atexit(void (* func)(void))
Registers the function pointed to by func, to be called without its arguments at normal program termination. It is possible to register at least 32 functions.
Returns: zero if the registration succeeds, non-zero if it fails.
void exit(int status)
Causes normal program termination to occur. If more than one call to the exit function is executed by a program (for example, by a function registered with atexit), the behaviour is undefined. First, all functions registered by the atexit function are called, in the reverse order of their registration. Next, all open output streams are flushed, all open streams are closed, and all files created by the tmpfile function are removed. Finally, control is returned to the host environment. If the value of status is zero or EXIT_SUCCESS, an implementation-defined form of the status 'successful termination' (0 under RISC OS) is returned. If the value of status is EXIT_FAILURE, an implementation-defined form of the status 'unsuccessful termination' (1 under RISC OS) is returned. Otherwise the status returned is implementation-defined (the value of status is returned under RISC OS).
char *getenv(const char * name)
Searches the environment list, provided by the host environment, for a string that matches the string pointed to by name. The set of environment names and the method for altering the environment list are implementation-defined.
Returns: a pointer to a string associated with the matched list member. The array pointed to is not modified by the program, but may be overwritten by a subsequent call to the getenv function. If the specified name cannot be found, a null pointer is returned.
int system(const char * string)
Passes the string pointed to by string to the host environment to be executed by a command processor in an implementation-defined manner. A null pointer may be used for string, to inquire whether a command processor exists. Under RISC OS, care must be taken, when executing a command, that the command does not overwrite the calling program. To control this, the string chain: or call: may immediately precede the actual command. The effect of call: is the same as if call: were not present. When a command is called, the caller is first moved to a safe place in application workspace. When the callee terminates, the caller is restored. This requires enough memory to hold caller and callee simultaneously. When a command is chained, the caller may be overwritten. If the caller is not overwritten, the caller exits when the caller terminates. Thus a transfer of control is effected and memory requirements are minimised.
Returns: If the argument is a null pointer, the system function returns non-zero only if a command processor is available. If the argument is not a null pointer, it returns an implementation-defined value (under RISC OS 0 is returned for success and -2 for failure to invoke the command; any other value is the return code from the executed command).
void *bsearch(const void *key, const void * base, size_t nmemb, size_t size, int (* compar)(const void *, const void *))
Searches an array of nmemb objects, the initial member of which is pointed to by base, for a member that matches the object pointed to by key. The size of each member of the array is specified by size. The contents of the array must be in ascending sorted order according to a comparison function pointed to by compar, which is called with two arguments that point to the key object and to an array member, in that order. The function returns an integer less than, equal to, or greater than zero if the key object is considered, respectively, to be less than, to match, or to be greater than the array member.
Returns: a pointer to a matching member of the array, or a null pointer if no match is found. If two members compare as equal, which member is matched is unspecified.
void qsort(void * base, size_t nmemb, size_t size, int (* compar)(const void *, const void *))
Sorts an array of nmemb objects, the initial member of which is pointed to by base. The size of each object is specified by size. The contents of the array are sorted in ascending order according to a comparison function pointed to by compar, which is called with two arguments that point to the objects being compared. The function returns an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second. If two members compare as equal, their order in the sorted array is unspecified.
div_t div(int numer, int denom)
Computes the quotient and remainder of the division of the numerator numer by the denominator denom. If the division is inexact, the resulting quotient is the integer of lesser magnitude that is the nearest to the algebraic quotient. If the result cannot be represented, the behaviour is undefined; otherwise, quot * denom + rem equals numer.
Returns: a structure of type div_t, comprising both the quotient and the remainder. The structure contains the following members: int quot; int rem. You may not rely on their order.
long int labs(long int j)
Computes the absolute value of an long integer j. If the result cannot be represented, the behaviour is undefined.
Returns: the absolute value.
ldiv_t ldiv(long int numer, long int denom)
Computes the quotient and remainder of the division of the numerator numer by the denominator denom. If the division is inexact, the sign of the resulting quotient is that of the algebraic quotient, and the magnitude of the resulting quotient is the largest integer less than the magnitude of the algebraic quotient. If the result cannot be represented, the behaviour is undefined; otherwise, quot * denom + rem equals numer.
Returns: a structure of type ldiv_t, comprising both the quotient and the remainder. The structure contains the following members: long int quot; long int rem. You may not rely on their order.
The behaviour of the multibyte character functions is affected by the LC_CTYPE category of the current locale. For a state-dependent encoding, each function is placed into its initial state by a call for which its character pointer argument, s, is a null pointer. Subsequent calls with s as other than a null pointer cause the internal state of the function to be altered as necessary. A call with s as a null pointer causes these functions to return a non-zero value if encodings have state dependency, and a zero otherwise. After the LC_CTYPE category is changed, the shift state of these functions is indeterminate.
int mblen(const char * s, size_t n)
If s is not a null pointer, the mblen function determines the number of bytes comprising the multibyte character pointed to by s. Except that the shift state of the mbtowc function is not affected, it is equivalent to mbtowc((wchar_t *)0, s, n).
Returns: If s is a null pointer, the mblen function returns a non-zero or zero value, if multibyte character encodings, respectively do or do not have state-dependent encodings. If s is not a null pointer, the mblen function either returns a 0 (if s points to a null character), or returns the number of bytes that comprise the multibyte character (if the next n of fewer bytes form a valid multibyte character), or returns -1 (if they do not form a valid multibyte character).
int mbtowc(wchar_t * pwc, const char * s, size_t n)
If s is not a null pointer, the mbtowc function determines the number of bytes that comprise the multibyte character pointed to by s. It then determines the code for value of type wchar_t that corresponds to that multibyte character. (The value of the code corresponding to the null character is zero). If the multibyte character is valid and pwc is not a null pointer, the mbtowc function stores the code in the object pointed to by pwc. At most n bytes of the array pointed to by s will be examined.
Returns: If s is a null pointer, the mbtowc function returns a non-zero or zero value, if multibyte character encodings, respectively do or do not have state-dependent encodings. If s is not a null pointer, the mbtowc function either returns a 0 (if s points to a null character), or returns the number of bytes that comprise the converted multibyte character (if the next n of fewer bytes form a valid multibyte character), or returns -1 (if they do not form a valid multibyte character).
int wctomb(char * s, wchar_t wchar)
Determines the number of bytes need to represent the multibyte character corresponding to the code whose value is wchar (including any change in shift state). It stores the multibyte character representation in the array object pointed to by s (if s is not a null pointer). At most MB_CUR_MAX characters are stored. If the value of wchar is zero, the wctomb function is left in the initial shift state).
Returns: If s is a null pointer, the wctomb function returns a non-zero or zero value, if multibyte character encodings, respectively do or do not have state-dependent encodings. If s is not a null pointer, the wctomb function returns a -1 if the value of wchar does not correspond to a valid multibyte character, or returns the number of bytes that comprise the multibyte character corresponding to the value of wchar.
The behaviour of the multibyte string functions is affected by the LC_CTYPE category of the current locale.
size_t mbstowcs(wchar_t * pwcs, const char * s, size_t n)
Converts a sequence of multibyte characters that begins in the initial shift state from the array pointed to by s into a sequence of corresponding codes and stores not more than n codes into the array pointed to by pwcs. No multibyte character that follow a null character (which is converted into a code with value zero) will be examined or converted. Each multibyte character is converted as if by a call to the mbtowc function. If an invalid multibyte character is found, mbstowcs returns (size_t)-1. Otherwise, the mbstowcs function returns the number of array elements modified, not including a terminating zero code, if any.
size_t wcstombs(char * s, const wchar_t * pwcs, size_t n)
Converts a sequence of codes that correspond to multibyte characters from the array pointed to by pwcs into a sequence of multibyte characters that begins in the initial shift state and stores these multibyte characters into the array pointed to by s, stopping if a multibyte character would exceed the limit of n total bytes or if a null character is stored. Each code is converted as if by a call to the wctomb function, except that the shift state of the wctomb function is not affected. If a code is encountered which does not correspond to any valid multibyte character, the wcstombs function returns (size_t)-1. Otherwise, the wcstombs function returns the number of bytes modified, not including a terminating null character, if any.
string.h declares one type and several functions, and defines one macro useful for manipulating character arrays and other objects treated as character arrays. Various methods are used for determining the lengths of the arrays, but in all cases a char * or void * argument points to the initial (lowest addresses) character of the array. If an array is written beyond the end of an object, the behaviour is undefined.
void *memmove(void * s1, const void * s2, size_t n)
Copies n characters from the object pointed to by s2 into the object pointed to by s1. Copying takes place as if the n characters from the object pointed to by s2 are first copied into a temporary array of n characters that does not overlap the objects pointed to by s1 and s2, and then the n characters from the temporary array are copied into the object pointed to by s1.
Returns: the value of s1.
char *strcpy(char * s1, const char * s2)
Copies the string pointed to by s2 (including the terminating null character) into the array pointed to by s1. If copying takes place between objects that overlap, the behaviour is undefined.
Returns: the value of s1.
char *strncpy(char * s1, const char * s2, size_t n)
Copies not more than n characters (characters that follow a null character are not copied) from the array pointed to by s2 into the array pointed to by s1. If copying takes place between objects that overlap, the behaviour is undefined. If terminating nul has not been copied in chars, no term nul is placed in s2.
char *strncat(char * s1, const char * s2, size_t n)
Appends not more than n characters (a null character and characters that follow it are not appended) from the array pointed to by s2 to the end of the string pointed to by s1. The initial character of s2 overwrites the null character at the end of s1. A terminating null character is always appended to the result.
Returns: the value of s1.
The sign of a non-zero value returned by the comparison functions is determined by the sign of the difference between the values of the first pair of characters (both interpreted as unsigned char) that differ in the objects being compared.
int memcmp(const void * s1, const void * s2, size_t n)
Compares the first n characters of the object pointed to by s1 to the first n characters of the object pointed to by s2.
Returns: an integer greater than, equal to, or less than zero, depending on whether the object pointed to by s1 is greater than, equal to, or less than the object pointed to by s2.
int strcmp(const char * s1, const char * s2)
Compares the string pointed to by s1 to the string pointed to by s2.
Returns: an integer greater than, equal to, or less than zero, depending on whether the string pointed to by s1 is greater than, equal to, or less than the string pointed to by s2.
int strncmp(const char * s1, const char * s2, size_t n)
Compares not more than n characters (characters that follow a null character are not compared) from the array pointed to by s1 to the array pointed to by s2.
Returns: an integer greater than, equal to, or less than zero, depending on whether the string pointed to by s1 is greater than, equal to, or less than the string pointed to by s2.
int strcoll(const char * s1, const char * s2)
Compares the string pointed to by s1 to the string pointed to by s2, both interpreted as appropriate to the LC_COLLATE category of the current locale.
Returns: an integer greater than, equal to, or less than zero, depending on whether the string pointed to by s1 is greater than, equal to, or less than the string pointed to by s2 when both are interpreted as appropriate to the current locale.
size_t strxfrm(char * s1, const char * s2, size_t n)
Transforms the string pointed to by s2 and places the resulting string into the array pointed to by s1. The transformation function is such that if the strcmp function is applied to two transformed strings, it returns a value greater than, equal to or less than zero, corresponding to the result of the strcoll function applied to the same two original strings. No more than n characters are placed into the resulting array pointed to by s1, including the terminating null character. If n is zero, s1 is permitted to be a null pointer. If copying takes place between objects that overlap, the behaviour is undefined.
Returns: The length of the transformed string is returned (not including the terminating null character). If the value returned is n or more, the contents of the array pointed to by s1 are indeterminate.
void *memchr(const void * s, int c, size_t n)
Locates the first occurrence of c (converted to an unsigned char) in the initial n characters (each interpreted as unsigned char) of the object pointed to by s.
Returns: a pointer to the located character, or a null pointer if the character does not occur in the object.
char *strchr(const char * s, int c)
Locates the first occurrence of c (converted to a char) in the string pointed to by s (including the terminating null character). The BSD UNIX name for this function is index().
Returns: a pointer to the located character, or a null pointer if the character does not occur in the string.
char *strpbrk(const char * s1, const char * s2)
Locates the first occurrence in the string pointed to by s1 of any character from the string pointed to by s2.
Returns: returns a pointer to the character, or a null pointer if no character form s2 occurs in s1.
char *strrchr(const char * s, int c)
Locates the last occurrence of c (converted to a char) in the string pointed to by s. The terminating null character is considered part of the string. The BSD UNIX name for this function is rindex().
Returns: returns a pointer to the character, or a null pointer if c does not occur in the string.
char *strtok(char * s1, const char * s2)
A sequence of calls to the strtok function breaks the string pointed to by s1 into a sequence of tokens, each of which is delimited by a character from the string pointed to by s2. The first call in the sequence has s1 as its first argument, and is followed by calls with a null pointer as their first argument. The separator string pointed to by s2 may be different from call to call. The first call in the sequence searches for the first character that is not contained in the current separator string s2. If no such character is found, then there are no tokens in s1 and the strtok function returns a null pointer. If such a character is found, it is the start of the first token. The strtok function then searches from there for a character that is contained in the current separator string. If no such character is found, the current token extends to the end of the string pointed to by s1, and subsequent searches for a token will fail. If such a character is found, it is overwritten by a null character, which terminates the current token. The strtok function saves a pointer to the following character, from which the next search for a token will start. Each subsequent call, with a null pointer as the value for the first argument, starts searching from the saved pointer and behaves as described above.
Returns: pointer to the first character of a token, or a null pointer if there is no token.
void *memset(void * s, int c, size_t n)
Copies the value of c (converted to an unsigned char) into each of the first n characters of the object pointed to by s.
Returns: the value of s.
char *strerror(int errnum)
Maps the error number in errnum to an error message string.
Returns: a pointer to the string, the contents of which are implementation-defined. Under RISC OS and Arthur the strings for the given errnums are as follows:
| 0 | No error (errno = 0) |
| EDOM | function argument out of range |
| ERANGE | function result not representable |
| ESIGNUM | illegal signal number to signal() or raise() |
| others | Error code (errno) has no associated message). |
The array pointed to may not be modified by the program, but may be overwritten by a subsequent call to the strerror function.
time.h declares two macros, four types and several functions for manipulating time. Many functions deal with a calendar time that represents the current date (according to the Gregorian calendar) and time. Some functions deal with local time, which is the calendar time expressed for some specific time zone, and with Daylight Saving Time, which is a temporary change in the algorithm for determining local time.
struct tm holds the components of a calendar time called the broken-down time. The value of tm_isdst is positive if Daylight Saving Time is in effect, zero if Daylight Saving Time is not in effect, and negative if the information is not available.
struct tm {
int tm_sec; /* seconds after the minute, 0 to 60
(0-60 allows for the occasional leap
second) */
int tm_min /* minutes after the hour, 0 to 59 */
int tm_hour /* hours since midnight, 0 to 23 */
int tm_mday /* day of the month, 0 to 31 */
int tm_mon /* months since January, 0 to 11 */
int tm_year /* years since 1900 */
int tm_wday /* days since Sunday, 0 to 6 */
int tm_yday /* days since January 1, 0 to 365 */
int tm_isdst /* Daylight Saving Time flag */
};
clock_t clock(void)
Determines the processor time used.
Returns: the implementation's best approximation to the processor time used by the program since program invocation. The time in seconds is the value returned, divided by the value of the macro CLOCKS_PER_SEC. The value (clock_t)-1 is returned if the processor time used is not available. In the desktop, clock() returns all processor time, not just that of the program.
double difftime(time_t time1, time_t time0)
Computes the difference between two calendar times: time1 - time0. Returns: the difference expressed in seconds as a double.
time_t mktime(struct tm * timeptr)
Converts the broken-down time, expressed as local time, in the structure pointed to by timeptr into a calendar time value with the same encoding as that of the values returned by the time function. The original values of the tm_wday and tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated above. On successful completion, the values of the tm_wday and tm_yday structure components are set appropriately, and the other components are set to represent the specified calendar time, but with their values forced to the ranges indicated above; the final value of tm_mday is not set until tm_mon and tm_year are determined.
Returns: the specified calendar time encoded as a value of type time_t. If the calendar time cannot be represented, the function returns the value (time_t)-1.
time_t time(time_t * timer)
Determines the current calendar time. The encoding of the value is unspecified.
Returns: the implementation's best approximation to the current calendar time. The value (time_t)-1 is returned if the calendar time is not available. If timer is not a null pointer, the return value is also assigned to the object it points to.
char *asctime(const struct tm * timeptr)
Converts the broken-down time in the structure pointed to by timeptr into a string in the style Sun Sep 16 01:03:52 1973\n\0.
Returns: a pointer to the string containing the date and time.
char *ctime(const time_t * timer)
Converts the calendar time pointed to by timer to local time in the form of a string. It is equivalent to asctime(localtime(timer)).
Returns: the pointer returned by the asctime function with that broken-down time as argument.
struct tm *gmtime(const time_t * timer)
Converts the calendar time pointed to by timer into a broken-down time, expressed as Greenwich Mean Time (GMT).
Returns: a pointer to that object or a null pointer if GMT is not available.
struct tm *localtime(const time_t * timer)
Converts the calendar time pointed to by timer into a broken-down time, expressed a local time.
Returns: a pointer to that object.
size_t strftime(char * s, size_t maxsize, const char *
format, const struct tm * timeptr)
Places characters into the array pointed to by s as controlled by the string pointed to by format. The format string consists of zero or more directives and ordinary characters. A directive consists of a % character followed by a character that determines the directive's behaviour. All ordinary characters (including the terminating null character) are copied unchanged into the array. No more than maxsize characters are placed into the array. Each directive is replaced by appropriate characters as described in the following list. The appropriate characters are determined by the LC_TIME category of the current locale and by the values contained in the structure pointed to by timeptr.
| Directive | Replaced by |
|---|---|
| %a | the locale's abbreviated weekday name |
| %A | the locale's full weekday name |
| %b | the locale's abbreviated month name |
| %B | the locale's full month name |
| %c | the locale's appropriate date and time representation |
| %d | the day of the month as a decimal number (01-31) |
| %H | the hour (24-hour clock) as a decimal number (00-23) |
| %I | the hour (12-hour clock) as a decimal number (01-12) |
| %j | the day of the year as a decimal number (001-366) |
| %m | the month as a decimal number (01-12) |
| %M | the minute as a decimal number (00-61) |
| %p | the locale's equivalent of either AM or PM designation associated with a 12-hour clock |
| %S | the second as a decimal number (00-61) |
| %U | the week number of the year (Sunday as the first day of week 1) as a decimal number (00-53) |
| %w | the weekday as a decimal number (0(Sunday) -6) |
| %W | the week number of the year (Monday as the first day of week 1) as a decimal number (00-53) |
| %x | the locale's appropriate date representation |
| %X | the locale's appropriate time representation |
| %y | the year without century as a decimal number (00-99) |
| %Y | the year with century as a decimal number |
| %Z | the time zone name or abbreviation, or by no character if no time zone is determinable |
| %% | %. |
If a directive is not one of the above, the behaviour is undefined.
Returns: If the total number of resulting characters including the terminating null character is not more than maxsize, the strftime function returns the number of characters placed into the array pointed to by s not including the terminating null character. Otherwise, zero is returned and the contents of the array are indeterminate.