|
SilverC Library Reference |
| Using the Run-Time Library This section describes the built-in Standard C library functions implemented in the SilverC environment. Any differences from the Standard are noted. Since the SilverC compiler does not keep internally the parameter and return types of the built-in functions, it is necessary to ensure that they are declared properly when you use them. The easiest way to do this is to use the distributed header files, which contain prototyped declarations for all of the built-in functions. Note: Since using an undeclared function will make it possible for parameter mismatch bugs to occur, we strongly recommend that you use the distributed header files, and turn on the compiler warnings option, so that the compiler catches undeclared function use. Run-Time Routines by Category SilverC predefined functions may be broken up into a number of categories: |
| Name | Description |
| memchr | find character in memory block |
| memcmp | compare memory blocks |
| memcpy | copy memory block |
| memmove | copy memory block |
| memset | set memory block to a byte value |
| Name | Description |
| isalnum | test character as alphanumeric |
| isalpha | test character as alphabetic |
| iscntrl | test character as control character |
| isdigit | test character as decimal digit |
| isgraph | test character as graphics character |
| islower | test character as lowercase |
| isprint | test character as printing character |
| ispunct | test character as punctuation |
| isspace | test character as whitespace |
| isupper | test character as uppercase |
| isxdigit | test character as hexadecimal digit |
| tolower | convert character to lowercase |
| toupper | convert character to uppercase |
| Name | Description |
| atof | convert text string to floating point |
| atoi | convert text string to integer |
| atol | convert text string to long integer |
| strtod | convert text string to double |
| strtol | convert text string to long integer |
| strtoul | convert text string to unsigned long integer |
| Name | Description |
| access | check for file or directory existence |
| remove | delete disk file |
| rename | rename disk file |
| unlink | delete disk file |
File Input and Output Functions
| Name | Description |
| clearerr | clear error and end-of-file flags for stream |
| fclose | close file stream |
| feof | test end-of-file flag for stream |
| ferror | test error flag for stream |
| fflush | flush output stream to disk |
| fgetc | read character from input stream |
| fgetpos | retrieve current file pointer in stream |
| fgets | read text string from input stream |
| filelength | return size of stream |
| fileno | return handle to stream |
| fopen | open file stream |
| fprintf | write formatted data to output stream |
| fputc | write character to output stream |
| fputs | write text string to output stream |
| fread | read bytes from input stream |
| fscanf | read formatted data from input stream |
| fseek | set file pointer in stream |
| fsetpos | set current file pointer in stream |
| ftell | retrieve current file pointer in stream |
| fwrite | write bytes to output stream |
| getc | read character from input stream |
| perror | print file error string on screen |
| printf | write formatted data to stdout |
| putc | write character to output stream |
| rewind | move file pointer to start of stream |
| sprintf | write formatted data to buffer |
| sscanf | read formatted data from buffer |
| tmpfile | create temp file for output |
| tmpnam | get name for temporary file |
| ungetc | push character back onto input stream |
| vfprintf | write formatted data to output stream |
| vprintf | write formatted data to stdout |
| vsprintf | write formatted data to buffer |
| Name | Description |
| abs | return integer absolute value |
| acos | return the arc-cosine of value |
| asin | return the arc-sine of value |
| atan | return the arc-tangent of value |
| atan2 | return the arc-tangent of value |
| ceil | return the smallest integer not less than x |
| cos | return the cosine of angle in radians |
| cosh | return the hyperbolic cosine of value |
| div | return a quotient/remainder pair from integer division |
| exp | return exponential function: ex |
| fabs | return floating point absolute value |
| floor | return largest integer not greater than x |
| fmod | return floating point remainder of x/y |
| frexp | split x into normalized fraction and a power of 2 |
| labs | return long integer absolute value |
| ldexp | return the function: x.2n |
| ldiv | return quotient/remainder pair from long integer division |
| log | return natural logarithm |
| log10 | return base 10 logarithm |
| modf | split x into integer and fractional parts |
| pow | return power function: xy |
| rand | generate pseudo-random number |
| sin | return the sine of angle in radians |
| sinh | return the hyperbolic sine of value |
| sqrt | return square root |
| srand | seed pseudo-random generator |
| tan | return the tangent of angle in radians |
| tanh | return the hyperbolic tangent of value |
| Name | Description |
| calloc | allocate and clear memory block from heap |
| free | return memory block to heap |
| malloc | allocate memory block from heap |
| realloc | change size of allocated memory block |
Process and Environment Control Functions
| Name | Description |
| exit | terminate program execution |
| getenv | retrieve environment string value |
| longjmp | restore execution context |
| setjmp | save current execution context |
| spawn | invoke program |
| Name | Description |
| assert | test program assertion |
| Name | Description |
| strcat | concatenate text strings |
| strchr | search text string for character, front-to-back |
| strcmp | compare text strings |
| strcpy | copy text string |
| strcspn | return length of prefix of text string of characters not in second string |
| strerror | return system error string |
| strlen | return length of text string |
| strlwr | convert text string to lowercase |
| strncat | concatenate text strings, length delimited |
| strncmp | compare text strings, length delimited |
| strncpy | copy text string, length delimited |
| strpbrk | search text string for characters in second string |
| strrchr | search text string for character, back-to-front |
| strspn | return length of prefix of text string of characters in second string |
| strstr | search text string for second string |
| strtok | break text string into tokens |
| strupr | convert text string to uppercase |
| Name | Description |
| asctime | convert time to string |
| clock | return time used by program |
| ctime | convert calendar time to local time |
| difftime | return difference between calendar times, in seconds |
| gmtime | convert calendar time to Greenwich Mean Time |
| localtime | convert calendar time to local time |
| mktime | convert local time to calendar time |
| strdate | copy date string to buffer |
| strftime | write formatted time and date information to buffer |
| strtime | copy time string to buffer |
| time | return current calendar time |
Variable Argument List Support
| Name | Description |
| va_arg | fetch next argument from variable argument list |
| va_end | end variable argument list processing |
| va_start | initialize variable argument list |
Predefined Variable
| int errno; errno is a system error number which may be consulted after certain C file operations or math functions. The values taken on by errno are defined in the header file errno.h. This identifier is to be used on the right-hand side of expressions in SilverC. The variable may not appear as the target of an assignment statement. The variable is predefined by SilverC and may not be declared in user programs. |
Standard C Run-Time Routines
abort
void abort( void )
| Synopsis | #include
"stdlib.h" The abort function terminates the currently executing program. |
| See Also | exit |
abs
int abs( int val )
int val; /* integer value */
| Synopsis | #include
"stdlib.h" The abs function returns the absolute value of val . |
| Parameters | val may be any integer number. |
| Return Value | The absolute value of val . |
| See Also | fabs, labs |
access
int access( char *filename, int mode
)
char *filename; // pathname of file or directory
int mode; // permission mode
| Synopsis | #include
"silver.h" The access function determines if path exists and can be accessed in access mode mode . |
||||||||||
| Parameters | filename
is a null-terminated string specifying the name of the file or path. mode is a
number specifying the access mode. The permissible values for mode are given by the
following table:
|
||||||||||
| Return Value | If path refers to a file, then access returns 0 if the file exists and can be accessed in mode. If path refers to a directory, access returns 0 if the directory exists. If path does not exist or is cannot be accessed by the specified mode, then access returns -1. | ||||||||||
| See Also | chdir , rmdir, rename, unlink |
acos
double acos( double x )
double x; /* double value */
| Synopsis | #include
"math.h" The acos function returns the value, in radians, of the arc cosine, or cos-1 of x . |
| Parameters | x must be in the range of [-1,1]. |
| Return Value | acos returns a value in the range of [0, p ], provided x is in the specified range; otherwise, acos returns 0.0, and sets errno (the system error variable) to EDOM. |
| See Also | cos |
char *asctime( struct tm *tp )
struct tm *tp; /* pointer to time structure */
| Synopsis | #include
"time.h" The asctime function converts the time contained in the tm struct pointed to by tp into a static string of 26 characters. The string is null-terminated, and takes the form: "Mon Feb 13 14:46:37 1995\n" |
| Parameters | tp is the address of a struct tm that holds time information, as filled in by localtime or gmtime. |
| Return Value | The address of the static string is returned. |
| Comments | The same static string is used by all calls to asctime, successive calls will overwrite it. |
| See Also | ctime, localtime , gmtime |
asin
double asin( double x )
double x; /* double value */
| Synopsis | #include
"math.h" The asin function returns the value, in radians, of the arc sine, or sin-1 of x. |
| Parameters | x must be in the range of [-1, 1]. |
| Return Value | asin returns a value in the range of [-p /2, p /2], if x is in the specified range; otherwise, asin returns 0.0, and sets errno (the system error variable) to EDOM. |
| See Also | sin |
assert
void assert( int
expression )
int expression; /* the assertion */
| Synopsis | #include
"assert.h" The assert macro evaluates the assertion denoted by expression and if it is zero (or false), and the special "no debug" identifier NDEBUG is not defined, causes an error message (which includes the name of the file, source line number, and text of the assertion) to be displayed on the screen, and then calls the abort function. Otherwise, no action is taken. |
| Parameters | expression is an integral expression, that should normally be non-zero; that is, in the normal course of program execution, the programmer would expect that the value of the expression is non-zero, and if it is zero, then this is a program logic error. |
| Comments | assert is implemented as a macro. |
| See Also | abort |
atan
double atan( double x )
double x; /* double value */
| Synopsis | #include
"math.h" The atan function returns the value, in radians, of the arc tangent, or tan-1 of x . |
| Parameters | x may be any value. |
| Return Value | atan returns a value in the range of (-p /2, p /2). |
| See Also | tan, atan2 |
atan2
double atan2( double y,
double x )
double y; /* double value */
double x; /* double value */
| Synopsis | #include
"math.h" The atan2 function returns the value, in radians, of the arc tangent, or tan-1 of y/x . |
| Parameters | x and y may not both be zero. |
| Return Value | if they x and y are both 0, then atan2 returns 0.0, and sets errno (the system error variable) to EDOM. Otherwise, atan2 returns a value in the range of [-p , p ]. |
| See Also | tan, atan |
atof
double atof( char *s )
char *s; /* string to be converted */
| Synopsis | #include
"stdlib.h" The atof function returns the value of an ASCII text string representation of a floating point number. atof stops reading the input string at the first character that it cannot recognize as part of a number. |
| Parameters | s should be a
null-terminated string with the following format: [whitespace][sign][digits][.digits][{e | E}[sign]digits] where whitespace is a sequence of tab or space characters, sign is either plus ('+') or minus ('-'), and digits are one or more decimal digits. |
| Return Value | If s is empty, or no digits are found, or if the only digits found are in the exponent (i.e. following the e or E), then atof returns 0. If the result cannot be represented, then the return value is undefined. |
| See Also | atoi, atol, strtod |
atoi
int atoi( char *s )
char *s; /* string to be converted */
| Synopsis | #include
"stdlib.h" The atoi function returns the value of an ASCII text string representation of an integer. atoi stops reading the input string at the first character that it cannot recognize as part of a number. |
| Parameters | s should be a
null-terminated string with the format [whitespace][sign][digits] where whitespace is a sequence of tab or space characters, sign is either plus ('+') or minus ('-'), and digits are one or more decimal digits. |
| Return Value | If s is empty, or no digits are found, then atoi returns 0. If the result overflows, then the return value is undefined. |
| See Also | atol, atof |
atol
long atol( char *s )
char *s; /* string to be converted */
| Synopsis | #include
"stdlib.h" The atol function returns the value of an ASCII text string representation of a long integer. atol stops reading the input string at the first character that it cannot recognize as part of a number |
| Parameters | s
should be a null-terminated string with the format [whitespace][sign][digits] where whitespace is a sequence of tab or space characters, sign is either plus ('+') or minus ('-'), and digits are one or more decimal digits. |
| Return Value | If s is empty, or no digits are found, then atol returns 0L. If the result overflows, then the return value is undefined. |
| See Also | atoi, atof, strtol, strtoul |
calloc
void *calloc( size_t n,
size_t s )
size_t n; /* number of items */
size_t s; /* number of bytes per item */
| Synopsis | #include
"stdlib.h" The calloc function attempts to allocate a piece of memory from the heap large enough to hold n items of size s. The memory is set to all zeros. |
| Parameters | n is the number of items requested. s is the size of each item, in bytes |
| Return Value | calloc returns a pointer to the beginning of the allocated memory, if successful, and a NULL pointer otherwise. |
| Comments | The memory allocated by calloc may be returned to the heap by using may be returned to the heap by using free. |
| See Also | free, malloc , realloc |
ceil
double ceil( double x
)
double x; /* double value */
| Synopsis | #include
"math.h" The ceil function calculates the smallest integer greater than or equal to x , as a double. |
| Parameters | x may be any value. |
| Return Value | ceil returns the calculated value. |
| See Also | floor |
chain
void chain ( char *name )
char *name; // .EX file name
| Synopsis | #include
"silver.h" The chain function halts the currently executing .EX file and transfers control to another .EX file specified by name. All open files (except the tfile) are closed. System variables are unchanged. Allocated memory is not freed. |
| Parameters | name is a null-terminated string, specifying the name of the .EX file to activate. |
| See Also | chain_and_return |
chain_and_return
void chain_and_return (
char *name )
char *name; // SilverC program name
| Synopsis | #include
"silver.h" The chain_and_return function halts the currently executing .EX file and transfers control to another .EX file specified by name. All open files (except the tfile) are closed. System variables are unchanged. Allocated memory is not freed. When the program specified by name terminates, control is transferred back to the program that called chain_and_return. |
| Parameters | name is a null-terminated string, specifying the name of the .EX file to activate. |
| See Also | chain |
clearerr
void clearerr( FILE
*fp )
FILE *fp; /* open stream pointer */
| Synopsis | #include
"stdio.h" The clearerr function clears the end-of-file and error flags for the stream associated with fp. |
| Parameters | fp is a pointer to an open stream. |
| See Also | feof, ferror |
clock
clock_t clock( void )
| Synopsis | #include
"time.h" The clock function returns the number of clock ticks that have elapsed since the current program began execution. The time in seconds may be approximated by dividing the return value by CLOCKS_PER_SEC (defined in time.h). |
| Return Value | The number of clock ticks is returned a clock_t (int). |
cos
double cos( double x
)
double x; /* angle in radians */
| Synopsis | #include
"math.h" The cos function returns the cosine of x, for x in radians. |
| Parameters | x may be any double value. |
| Return Value | cos returns a value in the range of [-1, 1]. |
| See Also | acos, dcos |
cosh
double cosh( double x
)
double x; /* a double value */
| Synopsis | #include
"math.h" The cosh function returns the hyperbolic cosine of x: (ex + e-x )/ 2. |
| Parameters | x may be any value. |
| Return Value | cosh returns a value greater than or equal to 1. If the magnitude of x is so large, such that cosh(x) cannot be represented, then the system error variable errno is set to ERANGE , and cosh returns HUGE_VAL. |
| See Also | sinh, tanh |
ctime
char *ctime( time_t
*tp )
time_t *tp; /* pointer to time_t value */
| Synopsis | #include
"time.h" The ctime function converts the time contained in the time_t pointed to by tp into a static string of 26 characters. The string is null-terminated, and takes the form: "Mon Feb 13 14:46:37 1995\n". |
| Parameters | tp is a pointer to a time_t , an arithmetic type defined in time.h, as obtainable by a call to time. |
| Return Value | The address of the static string is returned. |
| Comments | The same static string is
used by all calls to ctime, successive calls will overwrite it. ctime(tp) is equivalent to asctime(localtime(tp)). |
| See Also | time, asctime , localtime, gmtime |
difftime
double difftime(
time_t t2, time_t t1 )
time_t t2; /* ending time */
time_t t1; /* starting time */
| Synopsis | #include
"time.h" The difftime function computes the difference in time between t1 and t2 . |
| Parameters | t1 and t2 are time values, as obtained by time. |
| Return Value | difftime returns the double precision value of t2 - t1, expressed in seconds. |
| See Also | time |
exit
void exit( int val )
int val; /* exit value */
| Synopsis | #include
"stdlib.h" The exit function terminates the currently running SilverC program. |
| Parameters | val is any integral value. |
| Return Value | none; exit does not return to the caller. |
| Comments | SilverScreen does not currently make any use of the exit value, val. Also, there is no automatic freeing of allocated memory on exit of a SilverC program. |
| See Also | abort |
exp
double exp( double x
)
double x; /* a double value */
| Synopsis | #include
"math.h" The exp function evaluates the exponential function ex. |
| Parameters | x may be any value. |
| Return Value | The value of ex is returned; if overflow occurrs, then exp sets errno to ERANGE and returns HUGE_VAL; if underflow occurs, then exp sets errno to ERANGE and returns 0. |
| See Also | log |
fabs
double fabs( double x
)
double x; /* a double value */
| Synopsis | #include
"math.h" The fabs function computes the absolute value of x. |
| Parameters | x may be any value. |
| Return Value | fabs returns the absolute value. |
| See Also | abs, labs |
fclose
int fclose( FILE *fp
)
FILE *fp; /* stream pointer */
| Synopsis | #include
"stdio.h" The fclose function closes the open stream referred to by fp. |
| Parameters | fp is an open stream pointer. |
| Return Value | fclose returns 0 if the close was successful; and returns EOF (-1) otherwise. |
| See Also | fopen |
feof
int feof( FILE *fp )
FILE *fp; /* stream pointer */
| Synopsis | #include
"stdio.h" The feof function tests the end-of-file indicator for stream. |
| Parameters | fp is an open stream. |
| Return Value | feof returns a non-zero value if stream is at end-of-file; and 0 otherwise. |
| Comments | The end-of-file and error indicators for a stream may be cleared by clearerr. |
| See Also | ferror, clearerr |
ferror
int ferror( FILE *fp )
FILE *fp; /* stream pointer */
| Synopsis | #include
"math.h" The ferror function tests then error indicator for stream. |
| Parameters | fp is an open stream. |
| Return Value | ferror returns a non-zero value if the error indicator for stream is set. |
| Comments | The end-of-file and error indicators for a stream may be cleared by clearerr. |
| See Also | feof, clearerr |
fflush
int fflush( FILE *fp )
FILE *fp; /* output stream pointer */
| Synopsis | #include
"stdio.h" The fflush function causes any buffered data to be written to the output stream fp. |
| Parameters | fp is an open output stream pointer. |
| Return Value | fflush returns 0 if successful, and EOF (-1) otherwise. |
| See Also | fopen, fwrite, fclose |
fgetc
int fgetc( FILE *fp )
FILE *fp; /* input stream pointer */
| Synopsis | #include
"stdio.h" The fgetc function reads a character from the current location in the stream associated with fp. The current file pointer is updated. |
| Parameters | fp is an open input stream pointer. |
| Return Value | fgetc returns the character (as an integer) if successful, and EOF (-1) if not. |
| Comments | The fgetc function is identical to getc. |
| See Also | getc, fgets, fputc |
fgetpos
int fgetpos( FILE *fp,
fpos_t *pos )
FILE *fp; /* input stream pointer */
fpos_t *pos; /* structure to hold file position information */
| Synopsis | #include
"stdio.h" The fgetpos function retrieves the current position from fp and stores it into the structure pointed to by pos. This value may be subsequently used by fsetpos. |
| Parameters | fp is an open file stream. pos is the address of a file position structure (fpos_t is defined in stdio.h). |
| Return Value | fgetpos returns 0 if successful, and a non-zero value if not. |
| Comments | The fpos_t type is provided for recording file positions, where the possible length of the file is too large to be represented in a long integer. |
| See Also | fsetpos |
fgets
char *fgets( char *s, int
n, FILE *fp )
char *s; /* character buffer */
int n; /* maximum length */
FILE *fp; /* open input stream */
| Synopsis | #include
"stdio.h" The fgets function reads a string from stream fp, and stores it into the character buffer pointed to by s. fgets reads until either a newline or n-1 characters are encountered; the string is guaranteed to be null-terminated. |
| Parameters | s is the address of a character buffer, at least n bytes in length. fp is a stream pointer, open for input. |
| Return Value | fgets returns returns NULL (0L) if an error occurs or end-of-file is encountered before any characters have been read; otherwise, fgets returns s. |
| See Also | fputs, fgetc , fread |
filelength
long filelength( FILE *fp,
char *filepath )
FILE *fp; /* a stream pointer */
char *filepath; /* file path */
| Synopsis | #include
"stdio.h" The filelength function returns the length in bytes of a file. If fp is non-NULL, then filelength determines the length of the file referred to by fp ; otherwise, filelength determines the length of the file whose name is given by filepath . |
| Parameters | fp is an open stream,
or NULL. filepath is the name of a file on disk, or NULL. |
| Return Value | filelength returns the size in bytes of the indicated file. |
| Comments | If you wish to know the size
of an open file, use filelength as follows: filelength( fp, NULL ); If the file is not open, use filelength as follows: filelength( NULL, "\\some\\file\\name" ); |
fileno
int fileno( FILE *fp )
FILE *fp; /* an open stream */
| Synopsis | #include
"stdio.h" The fileno function returns the file handle to an open stream. |
| Parameters | fp is an open stream. |
| Return Value | fileno returns the file handle associated with fp. |
| Comments | This function is probably not very useful currently. |
floor
double floor( double x )
double x; /* a double value */
| Synopsis | #include "math.h"The floor function calculates the largest integer less than or equal to x, as a double. |
| Parameters | x is any value. |
| Return Value | floor returns the calculated value. |
| See Also | ceil |
fmod
double fmod( double x,
double y )
double x; /* a double value */
double y; /* a double value */
| Synopsis | #include
"math.h" The fmod function calculates the floating point remainder r of x / y , where r has the same sign as x, and |r| < |y|. That is, for some integer i, x = i * y + r. |
| Parameters | x and y are doubles, y may not be 0. |
| Return Value | fmod returns r . If x/y cannot be represented, the result is undefined. |
| See Also | modf, frexp |
fopen
FILE *fopen( char
*filename,char *mode )
char *filename; /* name of disk file */
char *mode; /* mode string */
| Synopsis | #include
"stdio.h" The fopen function opens a stream associated with the file specified by filename for I/O, according the the value of mode. |
||||||||||||||||||||||||
| Parameters | filename and mode
are null-terminated strings. mode must contain exactly one of "r",
"w" or "a", plus potentially a "+":
|
||||||||||||||||||||||||
| Return Value | fopen returns a non-NULL stream pointer if the file open succeeds, and NULL (0L) otherwise. | ||||||||||||||||||||||||
| See Also | fclose, fseek |
fprintf
int fprintf( FILE *fp,
char *fmt, ... )
FILE *fp; /* output stream pointer */
char *fmt; /* format string */
| Synopsis | #include
"stdio.h" The fprintf function writes text to the file associated with fp according to format string fmt. Arguments following fmt are formatted and printed in the output string. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Parameters | fp is a stream
pointer, open for output. fmt is a null-terminated string, containing format
conversion specifications. In the processing of fmt, when fprintf encounters
a conversion specification, it retrieves an argument and formats it into the output string
at that location, replacing the conversion specifier. All other characters are copied into
the output string.Conversion specifiers are introduced in the format string by the percent
character '%'. More specifically, conversion specifiers take the following form: %[flags][minimum field width][precision] [size specification][conversion]
Flags:
Conversion specifiers:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Return Value | fprintf returns the number of characters printed. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Comments | The types of arguments must match those expected by the format specifiers in fmt, and the number of arguments must be greater than or equal to the number of specifiers in fmt; otherwise, the result of fprintf is undefined. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See Also | printf, sprintf, ss_command |
fputc
int fputc( int c, FILE *fp
)
int c; /* a character, widened to int */
FILE *fp; /* output stream pointer */
| Synopsis | #include
"stdio.h" The fputc function writes the character c to the file associated with fp. |
| Parameters | c is a character. fp is a stream pointer, opened for output. |
| Return Value | fputc returns c if successful, or EOF (-1) if not. |
| Comments | fputc is identical to putc. |
| See Also | putc, fputs |
fputs
int fputs( char *s, FILE
*fp )
char *s; /* string to write */
FILE *fp; /* output stream pointer */
| Synopsis | #include
"stdio.h" The fputs function writes string s to the file associated with fp. |
| Parameters | s is a null-terminated string. fp is a stream pointer, opened for output. |
| Return Value | fputs returns a non-negative number if successful, and EOF (-1) if not. |
| See Also | fputc, fgets |
fread
size_t fread( void *buf,
size_t size, size_t n, FILE *stream )
void *buf; /* address of data buffer */
size_t size; /* size of each buffer element */
size_t n; /* number of buffer elements */
FILE *stream; /* input stream */
| Synopsis | #include
"stdio.h" The fread function reads n objects, each of size size bytes from the file associated with fp, and stores them in the buffer pointed to by buf. |
| Parameters | buf is the address of the buffer to receive the data, and should be at least size * n bytes in length. size and n are integers. stream is a stream pointer, open for input. |
| Return Value | fread returns the actual number of objects read, which will be less than or equal to n. |
| See Also | fgets, fwrite |
free
void free( void *buf )
void *buf; /* address of previously allocated buffer*/
| Synopsis | #include "stdlib.h" The free function returns the memory pointed to by buf to the heap. |
| Parameters | buf is a pointer which should have previously obtained by a call to malloc, calloc or realloc. |
| See Also | malloc, calloc, realloc |
frexp
double frexp( double x,
int *np )
double x; /* a double value */
int *np; /* address of integer to receive exponent value */
| Synopsis | #include "math.h" The frexp function splits the floating point number x into a fraction f and an exponent n such that x = f * pow( 2, n ), with (0.5 <= f < 1.0). |
| Parameters | x is any double. np is the address of an integer that is to receive the computed exponent. |
| Return Value | frexp returns f, and stores n into the integer pointed to by np. If x is 0.0, then both the return value and the value stored into np will also be 0. |
| See Also | fmod, modf |
fscanf
int fscanf( FILE *fp, char
*fmt, ... )
FILE *fp; /* stream pointer */
char *fmt; /* format string */
| Synopsis | #include
"stdio.h" The fscanf function reads from stream fp under control of format string fmt , and assigns converted values into subsequent arguments, each of which must be a pointer. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Parameters | fp is a stream
pointer, open for input. fmt is a null-terminated string, containing format
conversion specifications.Conversion specifiers take the following form: %[flags][minimum field width][precision] where:
Flags:
Conversion specifiers:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Return Value | fscanf returns EOF (-1) if end of file or error occurs before any conversion; otherwise it returns the number of items converted and assigned. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| See Also | sscanf, fprintf |
fseek
int fseek( FILE *stream,
long offset, int origin )
FILE *fp; /* stream pointer */
long offset; /* seek offset amount */
int origin; /* origin specifier */
| Synopsis | #include "stdio.h" The fseek function moves the file pointer for the file associated with fp to a location offset bytes a position specified by origin. |
||||||||||||
| Parameters | fp
is an open stream pointer. offset is a long value. origin is
one of the following (defined in stdio.h):
|
||||||||||||
| Return Value | fseek
returns 0 if successful, and EOF (-1) if not. |
||||||||||||
| Comments | Seeking past the end-of file is legal. | ||||||||||||
| See Also | ftell, fsetpos |
fsetpos
int fsetpos( FILE *fp,
fpos_t *pos )
FILE *fp; /* open stream pointer */
fpos_t *pos; /* structure to hold file position information */
| Synopsis | #include
"stdio.h" The fsetpos function sets the current file position in fp to the value held by the structure pointed to by pos, as retrieved by fsetpos. |
| Parameters | fp is an open file stream. pos is the address of a file position structure (fpos_t is defined in stdio.h). |
| Return Value | fsetpos sets the current file position and returns 0 if successful, and a non-zero value if not. |
| Comments | The fpos_t type is provided for recording file positions, where the possible length of the file is too large to be represented in a long integer. |
| See Also | fgetpos |
ftell
long ftell( FILE *stream )
FILE *fp; /* a stream pointer */
| Synopsis | #include
"stdio.h" The ftell function returns the value of the file pointer for the file associated with fp. |
| Parameters | fp is an open stream pointer. |
| Return Value | ftell returns the distance in bytes of the current file pointer if successful; and EOF (-1) if an error occurs. |
| See Also | fseek, fgetpos |
fwrite
size_t fwrite( void *buf,
size_t size, size_t n,FILE *stream )
void *buf; /* address of data buffer */
size_t size; /* size of each buffer element */
size_t n; /* number of buffer elements */
FILE *stream; /* output stream */
| Synopsis | #include "stdio.h" The fwrite function retrieves n objects, each of size size bytes, from the buffer pointed to by buf , and writes them into the file associated with fp. |
| Parameters | buf is the address of the buffer where the data is stored, and should be at least size * n bytes in length. size and n are integers. stream is a stream pointer, open for input. |
| Return Value | fwrite returns the actual number of objects written, which will be less than or equal to n. |
| See Also | fputs, fread |
getc
int getc( FILE *fp )
FILE *fp; /* input stream pointer */
| Synopsis | #include
"stdio.h" The getc function reads a character from the current location in the stream associated with fp. The current file pointer is updated. |
| Parameters | fp is an open input stream pointer. |
| Return Value | getc returns the character (as an integer) if successful, and EOF (-1) if not. |
| Comments | The getc function is identical to fgetc. |
| See Also | fgetc, putc |
getenv
char *getenv( char *name )
char *name; /* environment variable name */
| Synopsis | #include
"stdlib.h" The getenv function retrieves the environment string associated with the environment variable pointed to by name. |
| Parameters | name is a null-terminated string containing the name of the environment variable. |
| Return Value | If the environment variable denoted by name exists, getenv returns a pointer to a static buffer containing the associated environment string, the contents of which should not be modified by the programmer, and which may be overwritten by a subsequent call to getenv. Otherwise, getenv returns NULL. |
| See Also | get_env |
gmtime
struct tm *gmtime( time_t
*tp )
time_t *tp; /* address of time value */
| Synopsis | #include
"time.h" The gmtime function converts the time_t pointed to by tp into a struct tm, whose members represent a time in Greenwich Mean Time. |
| Parameters | tp is the address of a time_t containing a time value, as obtained by time. |
| Return Value | gmtime returns a pointer to a static struct tm if successful, which may be overwritten by subsequent calls to gmtime or localtime; and NULL if not. |
| See Also | localtime, time |
isalnum
int isalnum( int c )
int c; /* a character */
| Synopsis | #include
"ctype.h" The isalnum function determines whether c is a letter or digit. |
| Parameters | c is an int, whose value must be representable as a char. |
| Return Value | isalnum returns a non-zero value if c is a letter or digit, and 0 if not. |
isalpha
int isalpha( int c )
int c; /* a character */
| Synopsis | #include
"ctype.h" The isalpha function determines whether c is a letter. |
| Parameters | c is an int, whose value must be representable as a char. |
| Return Value | isalpha returns a non-zero value if c is a letter, and 0 if not. |
iscntrl
int iscntrl( int c )
int c; /* a character */
| Synopsis | #include
"ctype.h" The iscntrl function determines whether c is a control character (i.e. not a letter, digit, punctuation or space). |
| Parameters | c is an int, whose value must be representable as a char. |
| Return Value | iscntrl returns a non-zero value if c is a control character, and 0 if not. |
isdigit
int isdigit( int c )
int c; /* a character */
| Synopsis | #include
"ctype.h" The isdigit function determines whether c is a decimal digit. |
| Parameters | c is an int, whose value must be representable as a char. |
| Return Value | isdigit returns a non-zero value if c is a decimal digit, and 0 if not. |
isgraph
int isgraph( int c )
int c; /* a character */
| Synopsis | #include
"ctype.h" The isgraph function determines whether c is a printable character other than space (' '). |
| Parameters | c is an int, whose value must be representable as a char. |
| Return Value | isgraph returns a non-zero value if c is a printable character other than space, and 0 if not. |
islower
int islower( int c )
int c; /* a character */
| Synopsis | #include
"ctype.h" The islower function determines whether c is a lower-case letter. |
| Parameters | c is an int, whose value must be representable as a char. |
| Return Value | islower returns a non-zero value if c is a lower-case letter, and 0 if not. |
isprint
int isprint( int c )
int c; /* a character */
| Synopsis | #include
"ctype.h" The isprint function determines whether c is a printing character (i.e. a letter, digit, punctuation or space). |
| Parameters | c is an int, whose value must be representable as a char. |
| Return Value | isprint returns a non-zero value if c is a printing character, and 0 if not. |
ispunct
int ispunct( int c )
int c; /* a character */
| Synopsis | #include
"ctype.h" The ispunct function determines whether c is a punctuation character, (i.e. a printing character that is not a letter, digit or space). |
| Parameters | c is an int, whose value must be representable as a char. |
| Return Value | ispunct returns a non-zero value if c is a punctuation character, and 0 if not. |
isspace
int isspace( int c )
int c; /* a character */
| Synopsis | #include
"ctype.h" The isspace function determines whether c is a space character (i.e. a space (' '), form feed ('\f'), horizontal tab ('\t'), vertical tab ('\v'), newline ('\n') or carriage return ('\r')). |
| Parameters | c is an int, whose value must be representable as a char. |
| Return Value | isspace returns a non-zero value if c is a space character, and 0 if not. |
isupper
int isupper( int c )
int c; /* a character */
| Synopsis | #include
"ctype.h" The isupper function determines whether c is an uppercase letter. |
| Parameters | c is an int, whose value must be representable as a char. |
| Return Value | isupper returns a non-zero value if c is an uppercase letter, and 0 if not. |
isxdigit
int isxdigit( int c )
int c; /* a character */
| Synopsis | #include
"ctype.h" The isxdigit function determines whether c is a hexadecimal digit. |
| Parameters | c is an int, whose value must be representable as a char. |
| Return Value | isxdigit returns a non-zero value if c is a hexadecimal digit, and 0 if not. |
labs
long labs( long val )
long val; /* a long integer value */
| Synopsis | #include
"stdlib.h" The labs function returns the absolute value of val. |
| Parameters | val may be any long integer number. |
| Return Value | The absolute value of val. |
| See Also | abs, fabs |
ldexp
double ldexp( double x,
int n )
double x; /* a double value */
int n; /* an integer */
| Synopsis | #include
"math" The ldexp function calculates the value of the function: x * pow( 2, n ). If the result is too large to be represented in a double, errno is set to ERANGE. |
| Parameters | x is a double. n is an integer value. |
| Return Value | ldexp returns the value of the function. |
ldiv
ldiv_t ldiv( long n, long
d )
long n; /* numerator */
long d; /* divisor */
| Synopsis | #include
"stdlib.h" The ldiv function computes the quotient and remainder of the division of n by d. |
| Parameters | n and d may be any long integers; d may not be 0. |
| Return Value | ldiv returns a struct of type ldiv_t, containing the quotient and remainder, as defined in stdlib.h . If the result cannot be represented, the behavior of ldiv is undefined. |
| Comments | if d is 0, then the program will halt. |
| See Also | div |
localtime
struct tm *localtime(
time_t *tp )
time_t *tp; /* address of time value */
| Synopsis | #include
"time.h" The localtime function converts the time_t pointed to by tp into a struct tm, whose members represent a time in local time. |
| Parameters | tp is the address of a time_t containing a time value, as obtained by time. |
| Return Value | localtime returns a pointer to a static struct tm if successful, which may be overwritten by subsequent calls to gmtime or localtime; and NULL if not. |
| See Also | gmtime, time |
log
double log( double x )
double x; /* a double value */
| Synopsis | #include
"math.h" The log function calculates the natural logarithm of x , for x greater than 0. |
| Parameters | x is a double greater than 0. |
| Return Value | log returns the computed value if x is greater than 0. Otherwise, if x is negative log sets errno (the system error variable) to EDOM, or if x is 0, log sets errno to ERANGE. log returns a value equal to the negative of returns a value equal to the negative of HUGE_VAL (approximately -1.79769e+308) in both error cases. |
| See Also | log10, exp, pow |
log10
double log10( double x )
double x; /* a double value */
| Synopsis | #include
"math.h" The log10 function calculates the base 10 logarithm of x, for x greater than 0. |
| Parameters | x is a double greater than 0. |
| Return Value | log10 returns the computed value if x is greater than 0. Otherwise, if x is negative log10 sets errno (the system error variable) to EDOM, or if x is 0, log10 sets errno to ERANGE. log10 returns a value equal to the negative of returns a value equal to the negative of HUGE_VAL (approximately -1.79769e+308) in both error cases. |
| See Also | log, pow |
longjmp
void longjmp( jmp_buf env,
int val )
jmp_buf env; /* saved environment buffer */
int val; /* "return" value for setjmp */
| Synopsis | #include "setjmp.h" The longjmp function restores the execution context stored in env by a previous call to setjmp. Execution returns as if setjmp had returned val, with the exception that any global variables and variables local to the function containing the setjmp call retain the values that they had when longjmp was called. longjmp must be called before the function that called setjmp returns; otherwise, the state of the executing program is undefined (and will probably crash). |
| Parameters | env is the address of a "jump buffer" that has been previously initialized by a call to setjmp. val is is an integer signifying the "return" value for setjmp. |
| Comments | Since a true call to setjmp always returns 0, it would not be wise to use a value of 0 for val, since the setjmp caller could not then distinguish between returns via longjmp and setjmp returns. Standard C explicitly forbids longjmp to cause setjmp to return 0; SilverC does not yet have that restriction. |
| See Also | setjmp |
malloc
void *malloc( size_t size
)
size_t size; /* size in bytes of memory requested */
| Synopsis | #include
"stdlib.h" The malloc function attempts to allocate a piece of memory from the heap large enough to hold an object size bytes in length. |
| Parameters | size is an integer greater than zero. |
| Return Value | malloc returns a pointer to the beginning of the allocated memory, if successful, and a NULL pointer otherwise. |
| Comments | The memory allocated by malloc may be returned to the heap by using may be returned to the heap by using free. |
| See Also | free, calloc, realloc |
memchr
void *memchr( void *s, int
ch, size_t count )
void *s; /* memory to search in */
int ch; /* character to search for */
size_t count; /* size in bytes of search area */
| Synopsis | #include
"string.h" The memchr function searches for the first occurrence of ch in the count bytes beginning at s . |
| Parameters | s is the address of a memory buffer, at least count bytes in length. ch is any character value. |
| Return Value | memchr returns a pointer to the location where ch is found, if any, and NULL otherwise. |
| See Also | strchr |
memcmp
int memcmp( void *s1, void
*s2, size_t count )
void *s1; /* address of first memory buffer */
void *s2; /* address of second memory buffer */
size_t count; /* size in bytes of comparison */
| Synopsis | #include
"string.h" The memcmp function compares the count bytes starting at s1 with the count bytes beginning at s2. |
| Parameters | s1 and s2 are addresses of memory buffers at least count bytes in length. |
| Return Value | If the bytes at s1 are lexicographically less than those at s2, then memcmp returns a negative number; if the bytes at s1 are lexicographically greater than those at s2, then memcmp returns a positive number; otherwise they are equal, and memcmp returns 0. |
| See Also | strcmp |
memcpy
void *memcpy( void *s1,
void *s2, size_t count )
void *s1; /* address of target buffer */
void *s2; /* address of source buffer */
size_t count; /* number of bytes to copy */
| Synopsis | #include
"string.h" The memcpy function copies count characters from s2 to s1. s1 and s2 may not overlap. |
| Parameters | s1 and s2 are memory buffers at least count bytes in length. |
| Return Value | memcpy returns s1 . |
| See Also | memmove, strcpy |
memmove
void *memmove( void *s1, void
*s2, size_t count )
void *s1; /* address of target buffer */
void *s2; /* address of source buffer */
size_t count; /* number of bytes to copy */
| Synopsis | #include
"string.h" The memmove function copies count bytes from s2 to s1. s1 and s2 may overlap. |
| Parameters | s1 and s2 are memory buffers at least count bytes in length. |
| Return Value | memmove returns s1 . |
| See Also | memcpy, strcpy |
memset
void *memset( void *s, int
c, size_t count )
void *s; /* address of memory buffer */
int c; /* fill char */
size_t count; /* number of bytes to fill */
| Synopsis | #include
"string.h" The memset function fills the first count characters of buffer s with the character value of c. |
| Parameters | s is a memory buffer at least count bytes in length. c any character. |
| Return Value | memset returns s . |
mktime
time_t mktime( struct tm
*tp )
struct tm *tp; /* address of time structure */
| Synopsis | #include
"time.h" The mktime function constructs a value of type time_t from the time specified by the struct tm pointed to by tp. The components of tp must be valid. -1 is returned if tp cannot be converted. |
| Parameters | tp is the address of a time structure. |
| Return Value | mktime returns a time_t value corresponding to the time represented by tp, if successful, and -1 (cast to time_t) if tp is not convertible. |
| See Also | time, localtime , gmtime |
modf
double modf( double x,
double *ip )
double x; /* a double value */
double *ip; /* address of double to receive integer portion*/
| Synopsis | #include
"math.h" The modf function splits the floating point number x into an integer i and a fraction f (where fabs(f) < 1.0), with x, f and i all having the same sign. |
| Parameters | x is any double value. ip is the address of a double. |
| Return Value | modf stores i, converted to floating point, into the double pointed to by ip, and then returns f. |
| See Also | modf |
monitor
void monitor( int setting
)
int setting; /* enables/disables debugging monitor */
| Synopsis | #include
"silver.h" The monitor function enables or disables the debugging monitor function, depending on the value of setting. The debugging monitor function causes the name of a user function to be displayed on entry and exit of that function, if debugging information is included in the executable file. |
| Parameters | setting is 0 to disable the monitor function, and non-zero to enable it. |
perror
void perror( char *s )
char *s; /* message string */
| Synopsis | #include
"stdio.h" The perror function takes the string s and the string corresponding to the current value of errno and creates a message displayed on the screen, as if by the following code sequence:
char buf[128]; |
| Parameters | s is a null-terminated string containing a message. |
pow
double pow( double x,
double y )
double x; /* a double value */
double y; /* a double value */
| Synopsis | #include
"math.h" The pow function calculates the function xy . |
| Parameters | x and y is are double values such that if x is 0, then y must be greater than 0, or if x is less than 0, y must be integral. |
| Return Value | pow returns the value of the function. If error occurs, pow sets errno (the system error variable) to EDOM if x is 0 and y is negative, and returns HUGE_VAL (approximately 1.79769e+308). If x and y are both 0, or if x is less than 0 and y is not integral, then pow sets errno to EDOM and returns 0. If pow results in overflow, then errno is set to ERANGE and returns HUGE_VAL if x is positive, and negative HUGE_VAL if x is negative |
printf
int printf( char *fmt, ...
)
char *fmt; /* format string */
| Synopsis | #include
"stdio.h" The printf function writes data to stdout under control of the format string fmt. |
| Parameters | fmt is a null-terminated string that contains the desired format specifiers. |
| Return Value | printf returns the number of characters written, or a negative number if an error occurred. |
| Comments | Functions that write to stdout
, such as printf and vprintf, are not recommended for use in SilverC, since
the output of such functions may not be handled correctly by the graphics system used by
SilverScreen. The types of arguments must match those expected by the format specifiers in fmt, and the number of arguments must be greater than or equal to the number of specifiers in fmt; otherwise, the result of printf is undefined. |
| See Also | fprintf for a description of format specifiers acceptable to printf. sprintf, ss_command and vprintf are related functions. |
putc
int putc( int ch, FILE *fp
)
int c; /* a character, widened to int */
FILE *fp; /* output stream pointer */
| Synopsis | #include
"stdio.h" The putc function writes the character c to the file associated with fp. |
| Parameters | c is a character. fp is a stream pointer, opened for output. |
| Return Value | putc returns c if successful, or EOF (-1) if not. |
| Comments | putc is identical to fputc. |
| See Also | fputc, fputs |
rand
int rand( void )
| Synopsis | #include
"stdlib.h" The rand function returns a pseudo-random number. |
| Return Value | rand returns a pseudo-random number. The number is in the range from 0 to RAND_MAX (defined in stdlib.h). |
| Comments | srand may be used to "seed" the pseudo-random number generator that generates values returned by rand ; if rand is called before srand, the seed used will be 1. |
| See Also | srand |
realloc
void *realloc( void *p,
size_t s )
void *p; /* address of a previously allocated piece of memory */
size_t s; /* new size in bytes */
| Synopsis | #include
"stdlib.h" The realloc function changes the size of the object pointed to by p to the size indicated by s. The contents of p will be unchanged unless s is smaller than its original size. |
| Parameters | p is the address of a piece of memory previously allocated from the heap (as if by malloc, calloc, etc.). s is an integer specifying the new size of the memory block. |
| Return Value | realloc returns a pointer to the new region if successful, and NULL if not, in which case the contents of p are left unchanged. |
| See Also | malloc, calloc, free |
remove
int remove( char *filename
)
char *filename; /* name of file on disk */
| Synopsis | #include
"stdio.h" The remove function deletes the file with name filename. |
| Parameters | filename is a null-terminated string containing the name of the file to be deleted. |
| Return Value | remove returns 0 if successful; otherwise, errno will be set to an a non-zero value indicating the reason for failure, and that value will be returned. |
| Comments | remove is essentially identical to unlink, but remove is Standard C, while unlink is not. |
| See Also | unlink |
rename
int rename( char *oldname,
char *newname )
char *oldname; /* old filename */
char *newname; /* new filename */
| Synopsis | #include
"stdio.h" The rename function renames a file on disk. |
||||||||
| Parameters | oldname and newname are null-terminated strings containing the old and new names of the designated file, respectively. | ||||||||
| Return Value | rename returns 0 if
the function was successful. If an error occurred, then rename returns a negative
value, and sets errno (the system error variable) to one of the following:
|
||||||||
| See Also | remove, unlink |
rewind
void rewind( FILE *fp )
FILE *fp; /* open stream pointer */
| Synopsis | #include
"stdio.h" The rewind function resets a file stream to its beginning. |
| Parameters | fp is a pointer to an open stream. |
| Comments | rewind(fp) is equivalent to fseek(fp,0L,SEEK_SET). |
| See Also | fseek |
setjmp
int setjmp( jmp_buf env )
jmp_buf env; /* saved environment buffer */
| Synopsis | #include
"setjmp.h" The setjmp function stores the current execution context into env. |
| Parameters | env is the address of a "jump buffer", into which the current execution environment is stored. |
| Return Value | setjmp always returns 0 directly. However, a subsequent call to longjmp with the same jump buffer may be used to restore the saved execution context (i.e. returns control to the point after setjmp was called). If setjmp returns as a result of a call to longjmp , then it returns the val argument to longjmp. |
| See Also | longjmp |
sin
double sin( double x )
double x; /* angle in radians */
| Synopsis | #include
"math.h" The sin function returns the sine of x, for x in radians. |
| Parameters | x is may be any double value. |
| Return Value | sin returns a value in the range [-1, 1]. |
| See Also | asin, dsin |
sinh
double sinh( double x )
double x; /* a double value */
| Synopsis | #include
"math.h" The sinh function returns the hyperbolic sine of x: (ex - e-x )/ 2. |
| Parameters | x may be any value. |
| Return Value | sinh returns a value greater than or equal to 1. If the magnitude of x is so large, such that cosh(x) cannot be represented, then the system error variable errno is set to ERANGE, and sinh returns HUGE_VAL. |
| See Also | cosh, tanh |
sprintf
int sprintf( char *buf,
char *fmt, ... )
char *buf; /* character buffer to receive output */
char *fmt; /* format string */
| Synopsis | #include
"stdio.h" The sprintf function writes text to the character array at buf according to format string fmt. Arguments following fmt are formatted and printed in the output string. |
| Parameters | buf is the address of a character buffer that is to receive the output string. fmt is a null-terminated string containing format conversion specifications. |
| Return Value | sprintf returns the length of the string copied into buf. |
| Comments | The types of arguments must match those expected by the format specifiers in fmt, and the number of arguments must be greater than or equal to the number of specifiers in fmt; otherwise, the result of sprintf is undefined. |
| See Also | fprintf for a description of format specifiers acceptable to sprintf, printf and ss_command are related functions. |
sqrt
double sqrt( double x )
double x; /* a double value */
| Synopsis | #include
"math.h" The sqrt function calculates the square root of x. |
| Parameters | x is any non-negative double value. |
| Return Value | sqrt returns the square root of x, unless x is negative, in which case, sqrt sets errno (the system error variable) to EDOM, and then returns 0.0. |
srand
void srand( int seed )
int seed; /* ramdon number generator seed value */
| Synopsis | #include
"stdlib.h" The srand function prepares the pseudo-random number generator for a new sequence of random numbers. |
| Parameters | seed is any positive integral number. |
| Comments | If rand is called before srand, the seed used will be 1. |
| See Also | rand |
sscanf
int sscanf( char *buf,
char *fmt, ... )
char *buf; /* input string */
char *fmt; /* format string */
| Synopsis | #include
"stdio.h" The sscanf function the string at buf under control of format string fmt, and assigns converted values into subsequent arguments, each of which must be a pointer. |
| Parameters | buf is a null-terminated string containing the input string. fmt is a null-terminated string containing format conversion specifications. See the entry for fscanf for a description of permissible format specifiers. |
| Return Value | sscanf returns EOF (-1) if end of file or error occurs before any conversion; otherwise it returns the number of items converted and assigned. |
| See Also | fscanf, sprintf |
strcat
char *strcat( char *s1,
char *s2 )
char *s1; /* a string */
char *s2; /* a string */
| Synopsis | #include
"string.h" The strcat function concatenates string s2 onto the end of s1. |
| Parameters | s1 and s2 are null-terminated strings. |
| Return Value | strcat returns s1. |
| See Also | strncat |
strchr
char *strchr( char *s, int
ch )
char *s; /* a string */
int ch; /* search character */
| Synopsis | #include
"string.h" The strchr function searches string s for the first occurrence of ch. |
| Parameters | s is a null-terminated string. ch is a character. |
| Return Value | strchr returns a pointer to the first ccurrence of ch, if one exists, and NULL otherwise. |
| See Also | strrchr |
strcmp
int strcmp( char *s1, char
*s2 )
char *s1; /* a string */
char *s2; /* a string */
| Synopsis | #include
"string.h" The strcmp function compares strings s1 and s2. |
| Parameters | s1 and s2 are null-terminated strings. |
| Return Value | strcmp returns 0 if the two strings are identical. If s1 is lexicographically less than s2, then a negative value is returned; otherwise, a positive value is returned. |
| See Also | strncmp |
strcpy
char *strcpy( char *s1,
char *s2 )
char *s1; /* character buffer that is to receive string copy */
char *s2; /* string to copy */
| Synopsis | #include
"string.h" The strcpy function copies string s2 into the character buffer at s1, including s2's null-terminator. |
| Parameters | s1 is a character buffer that is to receive the string copy. s2 is a null-terminated string that is to be copied. |
| Return Value | strcpy returns s1. |
| See Also | strncpy |
strcspn
size_t strcspn( char *s1,
char *s2 )
char *s1; /* a string */
char *s2; /* string containing character set */
| Synopsis | #include
"string.h" The strcspn function determines of the prefix of string s1 that contains none of the characters in string s2. |
| Parameters | s1 and s2 are null-terminated strings. |
| Return Value | strcspn returns the length of the prefix determined above. |
| See Also | strspn |
strdate
char *strdate( char *buf )
char *buf; /* character buffer to receive date string */
| Synopsis | #include
"time.h" The strdate function copies the system date into buf as mm/dd/yy. |
| Parameters | buf is a character buffer that is to receive the date string. |
| Return Value | strdate returns buf. |
| See Also | strtime, strftime |
strerror
char *strerror( int error
)
int error; /* errno value */
| Synopsis | #include
"string.h" The strerror function returns a pointer to an error message corresponding to a value of the system error variable errno. |
| Parameters | error is a value of errno. |
| Return Value | strerror returns the pointer noted above. |
| Comments | The string contains a '\n' as its last non-null character. |
| See Also | perror |
strftime
size_t strftime( char *s,
size_t n, char *fmt, struct tm *tp )
char *s; /* character buffer to receive formatted time string */
size_t n; /* maximum count of characters to store */
char *fmt; /* format string */
struct tm *tp; /* address of time structure */
| Synopsis | #include
"time.h" The strftime function formats the time represented by the struct tm pointer tp into the character buffer pointed to by s, under control of the format string fmt. No more than n characters are stored in s , including the null-terminator. |
||||||||||||||||||||||||||||||||||||||||||||||
| Parameters | s is a character
buffer that is to receive the formatted time string. n is an integer specifying the
maximum number of characters to be stored into s. tp is the address of a struct
tm containing a time representation. fmt is a null-terminated string containing
ordinary characters and conversion specifications. Ordinary characters are copied
unmodified into s; conversion specifiers are replaced as described below. A conversion specification is a '%' character followed by a conversion character. The conversion specifications are the following:
|
||||||||||||||||||||||||||||||||||||||||||||||
| Return Value | strftime returns the number of characters stored in s, if less than n; otherwise, if the string would be larger than n, strftime returns 0. | ||||||||||||||||||||||||||||||||||||||||||||||
| See Also | strdate, strtime |
strlen
size_t strlen( char *s )
char *s; /* a string */
| Synopsis | #include
"string.h" The strlen function determines the length of the string s, not including the null-terminator. |
| Parameters | s is a null-terminated string. |
| Return Value | strlen returns the length of the string. |
strlwr
char *strlwr( char *s )
char *s; /* a string */
| Synopsis | #include
"string.h" The strlwr function converts each uppercase letter in s into its equivalent lowercase letter. |
| Parameters | s is a null-terminated string. |
| Return Value | strlwr returns s. |
strncat
char *strncat( char *s1,
char *s2, size_t count )
char *s1; /* a string */
char *s2; /* a string */
size_t count; /* maximum number of characters to append */
| Synopsis | #include
"string.h" The strncat function appends up to count characters from s2 to the end of s1. If a null character is encountered in s2 before count characters have been copied then the copying stops. s1 is then null-terminated. |
| Parameters | s1 and s2 are null-terminated strings. count is a positive integer. |
| Return Value | strncat returns s1. |
| See Also | strcat, strncpy |
strncmp
int strncmp( char *s1,
char *s2, size_t count )
char *s1; /* a string */
char *s2; /* a string */
size_t count; /* maximum number of characters to copare */
| Synopsis | #include
"string.h" The strncmp function compares up to count characters starting at s1 with the string at s2. If a null-terminator is encountered before count characters are compared, then the comparison stops. |
| Parameters | s1 and s2 are null-terminated strings. count is an integer specifying the maximum number of characters to compare. |
| Return Value | strncmp returns 0 if the strings are lexographically equal through their first count characters. Otherwise, if the string at s1 is lexicographically less than s2, then strncmp returns a negative number; if the string at s1 is lexicographically greater than s2, then strncmp returns a positive number. |
| See Also | strcmp |
strncpy
char *strncpy( char *s1,
char *s2, size_t count )
char *s1; /* a string */
char *s2; /* a string */
size_t count; /* maximum number of characters to copy */
| Synopsis | #include
"string.h" The strncpy function copies at most count characters from s2 into s1 . If there are less than count characters in s2, then after copying s2, s1 is padded with null characters to the length count. |
| Parameters | s1 and s2 are null-terminated strings. count is an integer specifying the maximum number of characters to copy. |
| Return Value | strncpy returns s1. |
| See Also | strcpy |
strpbrk
char *strpbrk( char *s1,
char *s2 )
char *s1; /* a string */
char *s2; /* character set string */
| Synopsis | #include
"string.h" The strpbrk function finds the first occurrence in string s1 of any character in string s2. |
| Parameters | s1 and s2 are null-terminated strings. |
| Return Value | strpbrk returns a pointer to the first occurrence in string s1 of any character in string s2 if any exists, and NULL otherwise. |
| See Also | strspn, strcspn |
strrchr
char *strrchr( char *s,
int ch )
char *s; /* a string */
int ch; /* search character */
| Synopsis | #include
"string.h" The strrchr function searches string s for the last occurrence of ch. |
| Parameters | s is a null-terminated string. ch is a character. |
| Return Value | strrchr returns a pointer to the first ccurrence of ch, if one exists, and NULL otherwise. |
| See Also | strchr |
strspn
size_t strspn( char *s1,
char *s2 )
char *s1; /* a string */
char *s2; /* character set string */
| Synopsis | #include
"string.h" The strspn function determines of the prefix of string s1 that consists only of characters in string s2. |
| Parameters | s1 and s2 are null-terminated strings. |
| Return Value | strspn returns the length of the prefix determined above. |
| See Also | strcspn, strpbrk |
strstr
char *strstr( char *s1,
char *s2 )
char *s1; /* a string */
char *s2; /* search string */
| Synopsis | #include
"string.h" The strstr function searches string s1 for the first occurrence of string s2. |
| Parameters | s1 and s2 are null-terminated strings. |
| Return Value | strstr returns a pointer to the first occurrence of s1 in s2, if one exists, and NULL otherwise. |
| See Also | strchr |
strtime
char *strtime( char *buf )
char *buf*; /* character buffer to receive time string */
| Synopsis | #include
"time.h" The strtime function copies the system date into buf as hh:mm:ss. |
| Parameters | buf is the address of a character buffer that is to receive the time string. |
| Return Value | strtime returns buf. |
| See Also | strdate, strftime |
strtod
double strtod( char *s,
char **p )
char *s; /* input string */
char **p; /* address of char pointer to receive last parse position */
| Synopsis | #include
"stdlib.h" The strtod function attempts to convert the prefix of the string s into a floating point value of type double, and returns that value. If p is not NULL, then a pointer to the location in s where the conversion left off is stored into the character pointer at p. Leading spaces in s are skipped. The number must consist of an optional '+' or '-', a sequence of decimal digits possibly containing a single decimal point, an optional exponent exponent part, consisting of the letter 'e' or 'E' , an optional sign, and a sequence of decimal digits. |
| Parameters | s is a null-terminated string. *p is the address of a character pointer that is to receive the ending position of the parse. |
| Return Value | strtod returns the floating point number. If the number would overflow, a range error is generated. |
| See Also | strtol, strtoul, atof |
strtok
char *strtok( char *s1,
char *s2 )
char *s1; /* input string */
char *s2; /* token string */
| Synopsis | #include
"string.h" A sequence of strtok calls may be used to split string s1 into tokens (sequences of characters not in string s2), separated by one or more characters from string s2. The first call to strtok should pass a non-NULL s1 . Subsequent calls should pass NULL, indicating to strtok that it is to continue from the end of the previous token. When a token is identified, a null character is written into the location where the next character from s2 is found following the token. |
| Parameters | s1 and s2 are null-terminated strings. |
| Return Value | A pointer to the start of the current token is returned; when no more tokens are found, NULL is returned. |
strtol
long strtol( char *s, char
**p, int base )
char *s; /* input string */
char **p; /* address of char pointer to receive last parse position */
int base; /* integer base */
| Synopsis | #include
"stdlib.h" The strtol function attempts to convert the prefix of the string s into a long int, and returns that value. If p is not NULL, then a pointer to the location in s where the conversion left off is stored into the character pointer at p. Leading spaces in s are skipped. The interpretation of s is affected by base : if it is zero, then the number should be formatted as a decimal, hexadecimal or octal constant (as in C); if it is between 2 and 36, inclusive, then the number must be formatted as a non-empty sequence of letters and digits in that base (with the letters 'a' ..'z' or 'A' ..'Z' representing digits for 10..36). Leading '+' or '-' signs are allowed. |
| Parameters | s is a null-terminated string. *p is the address of a character pointer that is to receive the ending position of the parse. base is an integer that specifies the numeric base in which the conversion is to occur. |
| Return Value | strtol returns the long integer converted. If the number would overflow, a range error is generated. |
| See Also | strtod, strtoul, atoi, atol |
strtoul
unsigned long strtoul(
char *s, char **p, int base )
char *s; /* input string */
char **p; /* address of char pointer to receive last parse position */
int base; /* integer base */
| Synopsis | #include
"stdlib.h" The strtoul function identical to strtol. |
| Parameters | s is a null-terminated string. *p is the address of a character pointer that is to receive the ending position of the parse. base is an integer that specifies the numeric base in which the conversion is to occur. |
| Return Value | strtol returns the long integer converted. If the number would overflow, a range error is generated. |
| See Also | strtod, strtol, atoi, atol |
strupr
char *strupr( char *s )
char *s; /* a string */
| Synopsis | #include
"string.h" The strupr function converts each lowercase letter in s into its equivalent uppercase letter. |
| Parameters | s is a null-terminated string. |
| Return Value | strupr returns s. |
| See Also | strlwr |
tan
double tan( double x )
double x; /* a double value */
| Synopsis | #include
"math.h" The tan function calculates the tangent of x, for x in radians. |
| Parameters | x may be any double value. |
| Return Value | tan returns the tangent of x. |
| See Also | sin, cos, atan, atan2 |
tanh
double tanh( double x )
double x; /* a double value */
| Synopsis | #include
"math.h" The tanh function calculates the hyperbolic tangent of x: (ex - e-x) / (ex + e-x). |
| Parameters | x is a double value. |
| Return Value | tanh returns the value calculated. If the absolute value of x is too large, then errno is set to ERANGE, and the value returned has magnitude equal to HUGE_VAL, with the same sign as x. |
| See Also | sinh, cosh |
time
time_t time( time_t *tp )
time_t *tp; /* address of time structure to receive time value */
| Synopsis | #include
"time.h" The time function returns the current calendar time in the arithmetic type time_t. If the pointer tp is not NULL, then the time is stored there, as well. |
| Parameters | tp is the address of a time_t value. |
| Return Value | time returns the current time as a time_t. |
| See Also | clock, difftime |
tmpfile
FILE *tmpfile( void )
| Synopsis | #include
"stdio.h" The tmpfile function creates a temporary file with open mode "wb+" (that is, create for reading and writing, binary mode). The file will be automatically deleted when it is closed, or when SilverScreen (not the .EX program) exits. |
| Return Value | tmpfile returns a pointer to the output stream (FILE *), or NULL if the file could not be created. |
| Comments | See the entry on fopen for information on open modes. |
| See Also | tmpnam |
tmpnam
char *tmpnam( char *s )
char *s; /* character buffer to receive file name */
| Synopsis | #include
"stdio.h" The tmpnam function may be used to create a unique filename that can be used in an fopen call. At most TMP_MAX unique filenames are guaranteed to be generated during program execution. |
| Parameters | s is the address of a character buffer that will receive the generated file name, or NULL. If s is non-NULL, then it must point to an array of not less that L_tmpnam characters; the resultant filename will be copied into s. |
| Return Value | If the call to tmpnam succeeds, then if s is NULL, tmpnam returns a pointer to a static buffer containing the filename; subsequent calls to tmpnam will alter that buffer; otherwise, the resultant file name will be copied into s, and tmpnam returns s. If an error occurs, tmpnam returns NULL. |
| See Also | tmpfile, fopen |
tolower
int tolower( int c )
int c; /* input char */
| Synopsis | #include
"ctype.h" The tolower function converts c to lowercase if it is an uppercase letter. |
| Parameters | c is the input character, expanded to an int. |
| Return Value | tolower returns the resultant character, expanded to an int. |
| See Also | toupper, strlwr |
toupper
int toupper( int c )
int c; /* input character */
| Synopsis | #include
"ctype.h" The toupper function converts c to uppercase if it is an lowercase letter. |
| Parameter | c is the input character, expanded to an int. |
| Return Value | toupper returns returns the resultant character, expanded to an int. |
| See Also | tolower, strupr |
ungetc
int ungetc( int c, FILE
*fp )
int c; /* a character */
FILE *fp; /* open input stream */
| Synopsis | #include
"stdio.h" The ungetc function pushes character c back onto stream fp, where it will be returned by the next read operation. Only one character of pushback is guaranteed per stream. |
| Parameters | c is a character, expanded to int size. fp is a stream pointer, open for input. |
| Return Value | ungetc returns EOF if an error occurred, and c otherwise. |
| See Also | fputc, getc |
va_arg
<data type> va_arg(
va_list args, <data type> )
va_list args; /* variable argument list */
<data type>; /* next argument data type */
| Synopsis | #include
"stdarg.h" The va_arg macro retrieves an argument of type <data type> based on the value of the va_list variable. |
| Parameters | args is the address of a va_list, used to hold the current location in a list of unnamed parameters. t is a data type (i.e. int, double *, etc.) that is the data type of the next argument in the argument list. |
| Return Value | va_arg returns a value of the data type specified by t. |
| Comments | The stdarg facility provides support for accessing unnamed arguments in functions with variable argument lists. The variable argument macros depend on the data type va_list (typedef'd from a char *), defined in stdarg.h, a variable of which may be used to step through the unnamed arguments. |
| See Also | va_start, va_end |
| Example // multicat: concatenate
strings void multicat( char *s1, ... ) |
|
va_end
void va_end( va_list args
)
va_list args; /* variable argument list */
| Synopsis | #include
"stdarg.h" The va_end macro is used to do any cleanup required for variable argument list processing. |
| Parameters | args is the address of a va_list, used to hold the current location in a list of unnamed parameters. |
| Comments | va_end should be called after all arguments have been read by va_arg. See the entry for va_arg for more information on the stdarg facility. |
| See Also | va_arg, va_start |
va_start
void va_start( va_list
args, <last arg name> )
va_list args; /* variable argument list */
<last arg name>; /* name of last named argument */
| Synopsis | #include
"stdarg.h" The va_start macro initializes the variable argument pointer args with the address of the first (named or unnamed) argument following the named argument <last arg name>. |
| Parameters | args is the address of a va_list, used to hold the current location in a list of unnamed parameters. |
| Comments | va_start must be called before any calls to va_arg or va_end. See the entry for va_arg for more information on the stdarg facility. |
| See Also | va_arg, va_end |
vfprintf
int vfprintf( FILE *fp,
char *fmt, va_list args )
FILE *fp; /* output stream pointer */
char *fmt; /* format string */
va_list args; /* argument list */
| Synopsis | #include
"stdio.h" #include "stdarg.h" The vfprintf function writes text to the file associated with fp according to format string fmt. The arguments for fmt are specified in the variable argument list args. |
| Parameters | fp is a stream pointer, open for output. fmt is a null-terminated string containing format specifications. args is of type va_list, a type suitable for holding information used by the variable argument macros. args should have been initialized by the va_start macro and perhaps modified by subsequent va_arg calls. |
| Return Value | vfprintf returns the number of characters printed. |
| Comments | vfprintf
is identical to fprintf, except that the variable argument list has been
replaced by the va_list args. The types of arguments must match those expected by the format specifiers in fmt, and the number of arguments must be greater than or equal to the number of specifiers in fmt; otherwise, the result of vfprintf is undefined. |
| See Also | fprintf for a description of permissible format specifiers. |
vprintf
int vprintf( char *fmt,
va_list args )
char *fmt; /* format string */
va_list args; /* argument list */
| Synopsis | #include
"stdio.h" #include "stdarg.h" The vprintf function writes data to stdout under control of the format string fmt. The arguments for fmt are specified in the variable argument list args. |
| Parameters | fmt is a null-terminated string that contains the desired format specifiers. args is of type va_list, a type suitable for holding information used by the variable argument macros. args should have been initialized by the va_start macro and perhaps modified by subsequent va_arg calls. |
| Return Value | vprintf returns the number of characters written, or a negative number if an error occurred. |
| Comments | vprintf
is identical to printf, except that the variable argument list has been
replaced by the va_list args. Functions that write to stdout, such as printf and vprintf, are not recommended for use in SilverC, since the output of such functions may not be handled correctly by the graphics system used by SilverScreen. The types of arguments must match those expected by the format specifiers in fmt, and the number of arguments must be greater than or equal to the number of specifiers in fmt; otherwise, the result of vprintf is undefined. |
| See Also | fprintf for a description of permissible format specifiers. |
vsprintf
int vsprintf( char *buf,
char *fmt, va_list args )
char *buf; /* address of character buffer to receive output */
char *fmt; /* format string */
va_list args; /* argument list */
| Synopsis | #include
"stdio.h" #include "stdarg.h" The vsprintf function writes text to the character array at buf according to format string fmt. The arguments for fmt are specified in the variable argument list args. |
| Parameters | buf is the address of a character buffer that is to receive the output string. fmt is a null-terminated string that contains the desired format specifiers. args is of type va_list, a type suitable for holding information used by the variable argument macros. args should have been initialized by the va_start macro and perhaps modified by subsequent va_arg calls. |
| Return Value | vsprintf returns the length of the string copied into buf. |
| Comments | vsprintf is identical
to sprintf, except that the variable argument list has been replaced by the va_list
args. The types of arguments must match those expected by the format specifiers in fmt, and the number of arguments must be greater than or equal to the number of specifiers in fmt; otherwise, the result of vsprintf is undefined. |
| See Also | fprintf for a description of permissible format specifiers. |