A Dictionary of ANSI Standard C Function Definitions

8/13/2019 A Dictionary of ANSI Standard C Function Definitions

1/63

A Dictionary of ANSI Standard C Function Definitions

ANSI STANDARD CFUNCTION DEFINITIONS

FOR THE CURIOUS

THE DESPERATETHE FRANTICAND THE SUICIDAL

Version 1.2.5

Updated 10 April 2005

The material contained in this ebook is not to be altered or copied without written permission from the author.Geoffrey Trott [email protected] reference Books

C PRIMA PLUS 4 EDITION by Stephen Prata (C99)THE STANDARD C LIBRARY by PJ Plauger (C89)

Baby Style Coupons

ABCDEFGILMOPQRSTUVW

LIBRARIESC89

file:///G|/learning/Books%20Computer/Ultimate%20C%20Material/A%20Dictionary%20of%20ANSI%20Standard%20C%20Function%20Definitions.htm (1 of 63) [21-06-2008 18:24:36]
http://www.allonlinecoupons.com/st/baby-style/http://www.allonlinecoupons.com/st/baby-style/http://www.amazingcounters.com/


2/63


assert.h ctype.h locale.h math.h setjmp.h signal.h

stdarg.h stddef.h stdio.h stdlib.h string.h time.h

C99

complex.h ctype.h fenv.h inttypes.h math.h stdarg.h

stdio.h stdlib.h string.h time.h wchar.h wctype.h

abort

void abort (void)

HEADER stdlib.h

PURPOSEThis function causes the program which calls it to end abruptly, unless SIGABRTis caught and the

interrupt handler function defined by signal() does not return.

RESULTNo values are returned by this function.

NOTESWhether files open when abort() is called are closed, or information contained withinbuffers linked to those files transferred, is implementation defined.abort() calls raise (SIGABRT), which returns an implementation

defined message confirming unsuccessful termination to the operating system.Although ANSI does not require it, many implementations display an error message of some kind.

SEE ALSO atexit() , exit() .

MENU LIBRARIES

abs

int abs (int num)

HEADER stdlib.h

PURPOSETo convert the value passed tonum into its absolute value.



3/63


RESULTIf successfulabs() returns the absolute value of the integernum,otherwise the value returned is implementation defined.

NOTESAn absolute value can be any NONnegative value includingZERO.

SEE ALSO div() , fabs() , labs() ,

ldiv() , C99 .

MENU LIBRARIES

acos

double acos (double angle)

HEADER math.h

PURPOSETo convert the double precision value passed to angle into its arc cosine.

RESULTIf successful, acos() returns the arc cosine of angle in radians, otherwise ifthe value returned by acos() is not a double, a range error (an illegal return value) will occur.Or if the value is too large to fit inside a double, acos() returns +or - HUGE_VAL, in either

case errno is set to ERANGE.

If the value is too small acos() returns 0.0, but whether errno is set toERANGEis implementation defined.

NOTESIf the value contained within angle is neither a double number, nor between -1 and 1.A domain error (an illegal argument) will occur, the global integer errno set to EDOM, and

an implementation defined value returned.

SEE ALSO asin() , atan() ,

atan2() , cos() , cosh() ,

sin() , sinh() , tan() ,

tanh() , C99 .

MENU LIBRARIES

asctime

char *asctime (const

struct tm *currtime)

HEADER time.h



4/63


PURPOSETo obtain the current date, in the form of weekday, month, day of the month, hour, minutes, seconds, year.This is then placed into a string 26characters long.

RESULTIf successful, asctime() returns a pointer to the buffer where the character stringhas been stored,otherwise the value it returns is implementation defined.

NOTES

Each time either asctime() , or ctime() is called, informationstored within the string may be overwritten.To initialise the tm structure pointed to bycurrtime , eitherlocaltime() , or

gmtime() must be called.

Thetm structure contains at least the following members in any order:

int tm_sec the number of seconds (0,60)

int tm_min the number of minutes (0,59)

int tm_hour the number of hours (0,23)

int tm_mday the day of the month (1,31)

inttm_month

the number of months since January (0,11)

int tm_year the number of years since 1900 (0,99)

int tm_wday the number of days since Sunday (0,6)

int tm_ydaythe number of days since January1st

(0,365)

inttm_isdst

the daylight savings time indicator

If the value oftm_isdst is GREATERthan or EQUALto 1, the daylight savingstime indicator is switched on.Or if the value oftm_isdst is ZEROthen the indicator is switched off.If the value of tm_isdst is negative the indicator is not being used.



5/63


SEE ALSO clock(), difftime(), time().

MENU LIBRARIES

asin

double asin (double angle)

HEADER math.h

PURPOSE

To convert the double precision value passed to angleinto its arc sine.

RESULTIf successful, asin()returns the arc sine of angle, in radians, otherwise if the value returned by asin()is not a double, a

range error (an illegal return value) will occur.

Or if the value is too large to fit inside a double, asin()returns +or - HUGE_VAL, in either case errnois set to ERANGE.

If the value is too small asin()returns 0.0, but whether errnois set toERANGEis implementation defined.

NOTES

If the value contained within angleis neither a double number, nor between -1 and 1.A domain error (a illegal argument) will occur, the global integer errnoset to EDOM, and an implementation defined

value returned.

SEE ALSO acos(), atan(), atan2(), cos(), cosh(),sin(),sinh(), tan(), tanh(), C99.

MENU LIBRARIES

assert

void assert (int comparison)

HEADER assert.h

PURPOSE

To help track down errors of logic within a program.

RESULT

No values are returned by this function.

NOTESassert()is implemented as a macro not a function.

If the assert()macro is replaced by a function, the behavior of that function is undefined.

If the result of the comparison is ZERO, assert()generates an implementation defined error message.

Showing the predefined macros_FILE_(the name of the file), and_LINE_ (the line where the error occurred),together with the values contained within comparison.

Following this it calls abort().



6/63


Otherwise assert()will allow the program to continue.

If you wish to switch assert()off, after the program has been tested for bugs, #define the macro NDEBUG.

SEE ALSO raise(),signal().

MENU LIBRARIES

atan

double atan (double angle)

HEADER math.h

PURPOSE

To convert the double precision value passed to angleinto its arc tangent.

RESULTatan()returns the arc tangent of angle, in radians, otherwise if the value returned by atan()is not a double, a range error

(an illegal return value) will occur.

Or if the value is too large to fit inside a double, atan()returns +or - HUGE_VAL, in either case errnois set to ERANGE.

If the value is too small atan()returns 0.0, but whether errnois set toERANGEis implementation defined.

NOTESIf the value contained within angleis not a double value, a domain error (an illegal argument) will occur, the global

integer errnoset to EDOM, andan implementation defined value returned.

SEE ALSO acos(), asin(), atan2(), cos(), cosh(),sin(),sinh(), tan(), tanh(), C99.

MENU LIBRARIES

atan2

double atan2 (double first, double second)

HEADER math.h

PURPOSE

To calculate the value of the arc tangent of firstdivided bysecond,using the signs of both arguments to calculate its quadrant.

RESULTIf successful, atan2()returns the value of the arc tangent in radians, otherwise if the value returned by atan2()is not a double,

a range error (an illegal return value) will occur.

Or if the value is too large to fit inside a double, atan2()returns +or - HUGE_VAL, in either case errnois set to ERANGE.

If the value is too small atan2()returns 0.0, but whether errnois set toERANGEis implementation defined.

NOTESIf the values of bothfirstandseconddo not contain double precision numbers, or contain ZERO.

A domain error (an illegal argument) will occur, the global integer errnoset to EDOM, andan implementation defined



7/63


value returned.

SEE ALSO acos(), asin(), atan(), cos(), cosh(),sin(),sinh(), tan(), tanh(), C99.

MENU LIBRARIES

atexit

int atexit (void(*func)(void))

HEADER stdlib.h

PURPOSE

The function pointed to byfunc(),will be called when the program terminates normally.

RESULTatexit()returns ZEROif the function exists and can be nominated.

Otherwise a NON ZEROvalue is returned.

NOTESANSIallows a minimum of 32 termination functions to be nominated.

They are called in reverse order by exit(), these functions cannot have parameters.

SEE ALSO abort(),getenv(),system().

MENU LIBRARIES

atof

double atof (const char *string)

HEADER stdlib.h

PURPOSE

To convert the character array pointed to bystringinto a double precision value.

RESULTIf successful, atof()returns a double value.

Otherwise its behavior is implementation defined, it does not have to change the value of the global integer errno.

NOTESIf *stringdoes not contain a floating point number, the value returned cannot be used.

The character array must contain the following in this order:-

[WHITE SPACE SIGN] INTEGER DECIMAL POINT INTEGER [d,D,e,E SIGN INTEGER]



8/63


AWHITE SPACE consists of an optional space and or a tab character, which are both ignored.

SIGNis either +or -, and is also optional.

INTEGERmay contain one or more decimal numbers.

If no numbers appear before theDECIMAL POINTthen at least one must appear after it.

The numbers may be followed by an exponent, which consists of an introductory letter, either d, D, e, or Eand an

optional signed integer.

The character array will be processed by atof(),until the function reaches a character which it doesn't recognize, this includes

`\0`.

SEE ALSO atoi(), atol(),strtod(),strtol(),strtoul().

MENU LIBRARIES

atoi

int atoi (const char *string)

HEADER stdlib.h

PURPOSE

To convert the contents of the character array, pointed to bystringinto an integer value.

RESULTIf successful, atoi()returns an integer value.


NOTESThe character array pointed to bystringmust contain the following in this order:-

[WHITE SPACE SIGN] INTEGER

AWHITE SPACE consists of an optional space and or a tab character, which are both ignored.



The character array is processed by atoi()until the function reaches a character which it does not recognise , this includes `\0`.

atoi()does not recognise decimal points or exponents.

SEE ALSO atof(), atol(),strtod(),strtol(),strtoul().

MENU LIBRARIES



9/63


atol

long int atol (const char *string)

HEADER stdlib.h

PURPOSE

To convert the character array pointed to bystringinto a long integer.

RESULTIf atol()returns a long integer.


NOTESThe character array pointed to bystringmust contain a long integer value, and take the form:-

[WHITE SPACE SIGN] LONG INTEGER

AWHITE SPACEconsists of an optional space and or a tab character, which are both ignored.



The character array will then be processed by atol()until the function reaches a character which it doesn't recognise,

this includes `\0`.

atol()does not recognise decimal points or exponents.

SEE ALSO atof(), atoi(),strtod(),strtol(),strtoul().

MENU LIBRARIES

bsearch

void *bsearch (const void *key1, const void *buffer, size_tlength, size_t width,

int (*compare) (const void *key2, const void *elem))

HEADER stdlib.h

PURPOSETo perform a binary search on the sorted array pointed to by buffer, until a match is found with the character pointed to

by key1.

Where lengthis the number of array elements, and widththe size in bytes of each element.

comparepoints to a user defined function, which carries out the actual comparison.

key2points to the same character pointed to by key1within bsearch(), while elempoints to an individual element within

the sorted array.

RESULTIf successful, bsearch()itself returns a generic pointer, containing the address of the first match with *key2, otherwise it


f S S d d C f


10/63


returns the macro NULL(a NULL pointer).

The user defined function pointed to by compareis called at least once by bsearch().

Each time (*compare ()) tests the value within the array element pointed to by elem, to check whether it matches the

value pointed to by key2.

It must return one of the following three values:-

Less thanZERO

If *key2 is less than *elem

ZERO If *key2 is equal to *elem

More thanZEROIf *key2 is greater than*elem

NOTESThe array being searched must be sorted in ascending order, with the lowest array element containing the lowest value.

It must not contain duplicate records with identical keys.

SEE ALSO qsort().

MENU LIBRARIES

calloc

void *calloc (size_tnum, size_t length)

HEADER stdlib.h

PURPOSE

To allocate an area of memory for an array of elements.

Where numis the number of individual elements and lengththeir size in bytes.

RESULTIf successful, calloc()returns a generic pointer to the beginning of the area of memory allocated. Otherwise it returns the

macro NULL(a NULL pointer).

NOTES

Unlike malloc(), calloc()initialises all the bits within the array to ZERO.

SEE ALSO free(), realloc().

MENU LIBRARIES

file:///G|/learning/Books%20Computer/Ultimate%20C%20Material/A%2...ctionary%20of%20ANSI%20Standard%20C%20Function%20Definitions.htm (10 of 63) [21-06-2008 18:24:36]

A Di ti f ANSI St d d C F ti D fi iti


11/63


ceil

double ceil (double upwards)

HEADER math.h

PURPOSE

To calculate the double precision value passed to upwards, rounded up to its next whole number.

RESULTIf successfulceil()returns a double value, rounded up to the next whole number, otherwise if the value returned by ceil()isnot a double, a range error (an illegal return value) will occur.

Or if the value is too large to fit inside a double, ceil()returns +or - HUGE_VAL, in either case errnois set to ERANGE.

If the value is too small ceil()returns 0.0.

When a domain error occurs, an implementation defined value is returned.

NOTESIf the value contained within upwards is not a double.

A domain error (an illegal argument) will occur, and the global integer errnoset to EDOM.

SEE ALSO fabs(),floor(),fmod().

MENU LIBRARIES

clearerr

void clearerr (FILE *file_pointer)

HEADER stdio.h

PURPOSE

To switch the file error flag off, and to reset the End Of File indicator associated with the file pointed to byfile_pointer.

RESULT


SEE ALSO feof(),ferror(),fgetpos(),ftell(),fseek(),fsetpos(),perror(), rewind().

MENU LIBRARIES

clock

clock_t clock (void)

HEADER time.h

PURPOSE




12/63


To find out how long a distinct process within a program has been running.

RESULTIf successful, clock()returns the amount of time the entire program has been running, as an variable of typeclock_t,

otherwise it returns (clock_t)-1.

NOTES

To convert the value returned by clock()into seconds divide it by the macro CLOCKS_PER_SEC .

SEE ALSO asctime(), ctime(), difftime(),gmtime(), localtime(), mktime(),strftime(), time().

MENU LIBRARIES

cos

double cos (double angle)

HEADER math.h

PURPOSE

To convert the double precision value passed to angleinto its cosine.

RESULTIf successful, cos()returns the cosine of angle, in radians, otherwise if the value returned by cos()is not a double, a range

error (an illegal return value) will occur.

Or if the value is too large to fit inside a double, cos()returns +or - HUGE_VAL, in either case errnois set to ERANGE.

If the value is too small cos()returns 0.0, but whether errnois set toERANGEis implementation defined.

NOTESIf the value contained within angleis not a double number, a domain error (an illegal argument) will occur, the global

integer errnoset to EDOM, and an implementation defined value returned.

SEE ALSO acos(), asin(), atan(),atan2(), cosh(),sin(),sinh(), tan(), tanh(), C99.

MENU LIBRARIES

cosh

double cosh (double angle)

HEADER math.h

PURPOSE

To convert the double precision value passed to angleinto its hyperbolic cosine.

RESULTIf successful, cosh()returns the hyperbolic cosine of angle, in radians, otherwise if the value returned bycosh()is not a

double, a range error (an illegal return value) will occur.




13/63


Or if the value is too large to fit inside a double, cosh()returns +or - HUGE_VAL, in either case errnois set to ERANGE.

If the value is too smallcosh()returns 0.0, but whether errnois set toERANGEis implementation defined.

NOTESIf the value contained within angleis not a double number, a domain error (an illegal argument) will occur, the global

integer errnoset to EDOM, and an implementation defined value returned. .

SEE ALSO acos(), asin(), atan(), atan2(), cos(),sin(),sinh(), tan(), tanh(), C99.

MENU LIBRARIES

ctime

char *ctime (const time_t *num_seconds)

HEADER time.h

PURPOSETo obtain the local time in the form of weekday, month, day of month, year, hours, minutes, seconds.

Which is placed in a string 26characters long.

RESULTIf successful, ctime()returns a pointer to the buffer, where the character string has been stored, otherwise it returns

an implementation defined value.

NOTESBefore calling ctime() num_seconds,a pointer to the calendar time, must be obtained by calling time().

The calendar time is stored as a object of type time_t, containing an implementation defined variable.

Each time either asctime(), or ctime(), is called, information stored within the string may be overwritten.

SEE ALSO clock(), difftime().

MENU LIBRARIES

difftime

double difftime (time_t end, time_t begin)

HEADER time.h

PURPOSETo calculate the difference in seconds between the value passed to end(the end of a period of time), and that passed to

begin(the beginning).

RESULT

If successful, difftime()returns a double precision value, containing the time difference in seconds.

NOTES




14/63


time_tis an object which stores time as an implementation defined variable.

The values contained within beginand endcan be obtained by calling clock()on two separate occasions.

SEE ALSO asctime(), clock(), ctime(),gmtime(), localtime(), mktime(),strftime(), time().

MENU LIBRARIES

div

div_t div (int number, int divider)

HEADER stdlib.h

PURPOSE

To divide the value passed to number, by the value contained in divider.

RESULTIf successful, div() returns a div_tstructure containing both the quotient, and the remainder of the division as two

separate values, otherwise the value returned is implementation defined..

NOTESIf the value contained in divideris

ZERO, the behavior is implementation defined.

However, many implementations terminate with an error message.

The div_tstructure contains the following members, although they do not have to appear in that order:

typedef struct

{ int quot;

int rem; }

div_t div

SEE ALSO abs(),labs(), ldiv()

MENU LIBRARIES

exit

void exit (int exit_code)

HEADER stdlib.h

PURPOSE

To terminate the program which calls it.

RESULT


NOTESexit()can be executed only once within a program.




15/63


If the value passed toexit_codeis ZEROor EXIT_SUCCESS then the program has terminated normally, any

other implementation defined value indicates an error of some kind.

The other macro used by exit_code is EXIT_FALSE.

When exit()is called any functions nominated by atexit()will be called in their reverse order.

Any files which are still open will be closed, after the buffers linked to them have been emptied.

All temporary files created by tmpfile()are deleted.

SEE ALSO abort(),

MENU LIBRARIES

exp

double exp (double num)

HEADER math.h

PURPOSE

To calculate the natural logarithme, raised to the power of num.

RESULT

If successful, exp()returns a double precision value containing e to the power of num, otherwise if the value returned by exp()is not a double, a range error (an illegal return value) will occur.

Or if the value is too large to fit inside a double, exp()returns +or - HUGE_VAL, in either case errnois set to ERANGE.

If the value is too small exp()returns 0.0.


NOTESIf the value contained within numis not a double, a domain error (an illegal argument) will occur, and the global integer

errnoset to EDOM.

SEE ALSO log, C99.

MENU LIBRARIES

fabs

double fabs (double num)

HEADER math.h

PURPOSE

To calculate the absolute (e.g positive) value of num.

RESULTIf successfulfabs()returns the absolute value of numas a double precision number, otherwise if the value returned byfabs()

is not a double, a range error (an illegal return value) will occur.

Or if the value is too large to fit inside a double,fabs()returns +or - HUGE_VAL, in either case errnois set to ERANGE.




16/63

y

If the value is too smallfabs()returns 0.0.


NOTESThe absolute value of a number can only be positive.

If the value contained within numis not a double, a domain error (an illegal argument) will occur, and the global integer

errnoset to EDOM.

SEE ALSO abs(), ceil(),floor(),fmod(), labs().

MENU LIBRARIES

fclose

int fclose (FILE *file_pointer)

HEADER stdio.h

PURPOSE

To close the file pointed to byfile_pointer.

RESULT

If successful,fclose()will return ZERO. Otherwise it returns EOF.

NOTESInformation in the buffer pointed to byfile_pointerwill be emptied, and its contents flushed to that particular file.

However, data which is waiting to be read will be discarded.

SEE ALSO fflush(),fopen(),freopen().

MENU LIBRARIES

feof

int feof (FILE *file_pointer)

HEADER stdio.h

PURPOSE

To check whether the end of the file pointed to byfile_pointerhas been reached.

RESULTIf the The End Of File indicator has been set,feof()will return NON ZERO.

Otherwise it returns ZERO.

NOTESfeof()is often used when working with binary files.

Calling clearerr(),fseek(),fsetpos(),or rewind()will clear the EOFindicator.




17/63

SEE ALSO ferror(),perror().

MENU LIBRARIES

ferror

int ferror (FILE *file_pointer)

HEADER stdio.h

PURPOSE

To check for read/writeerrors in the file pointed to byfile_pointer.

RESULT

If an error has been detectedferror()will return NON ZERO.

NOTESThose error flags linked tofile_pointerwill remain set until eitherfclose(), rewind(),or clearerr()are called.

ferror()is often used when checking for errors in binary files.

SEE ALSO feof(),perror().

MENU LIBRARIES

fflush

int fflush (FILE *file_pointer)

HEADER stdio.h

PURPOSE

To empty the contents of the output buffer, into the file pointed to byfile_pointer.

RESULT

If successful,fflush()returns ZERO, otherwise it returns EOF.

NOTESTo flush ALL output buffers call fflush(NULL).

If the file has been opened for read/write, a read may not be followed by a write.

Or vice versa, without first calling eitherfflush(),fseek(),fsetpos(), orrewind().

SEE ALSO fclose(),fopen(),freopen(),setbuf(),setvbuf().

MENU LIBRARIES

fgetc




18/63

int fgetc (FILE *file_pointer)

HEADER stdio.h

PURPOSE

To obtain the next character from the file pointed to byfile_pointer, and increment the file position indicator.

RESULT

If successful,fgetc()will return the numerical value of the character read. Otherwise it will return EOF.

NOTESfgetc()will also return EOFin the event of a read error.

When working with binary files,feof()must be called, to check that the End Of File position has been reached, andferror()

to check for errors.


Or vice versa, without first calling eitherfflush(),fseek(),fsetpos(), or rewind(), unless EOFwas the last character read by

fread()

SEE ALSO fgets(),fputc(),fputs(),fwrite(),getc(),getchar(),gets(),putc(),putchar(),puts().

MENU LIBRARIES

fgetpos

int fgetpos (FILE *file_pointer,fpos_t*position)

HEADER stdio.h

PURPOSETo obtain the location of the file position indicator linked to *file_pointer, this value will then be stored in the area of

memory pointed to byposition.

RESULTIf successful,fgetpos()will return ZERO, otherwise it returns NON ZEROstoring an implementation defined positive

value in the global integer errno.

NOTES

The information stored inpositioncan be used later byfsetpos()to return the file position indicator to its former location.

SEE ALSO fflush(),fseek(),ftell(), rewind(),C99.

MENU LIBRARIES

fgets

char *fgets (char *string, int width, FILE *file_pointer)




19/63

HEADER stdio.h

PURPOSETo read a line of width- 1 number of characters long into the buffer pointed to bystring, from the file pointed to

byfile_pointer.

RESULT

If successful,fgets()will return the address of the input buffer, otherwise it returns the macro NULL(a NULL pointer).

NOTES

fgets()will continue to read characters until either the '\n' or EOFcharacter is received.If the length of the line of characters is less than width, the '\n' character will be copied into *string.

At the end of the string an '\0' character is added.

To check whether an error has occurred or the EOF character has been reached, eitherfeof()orferror()needs to be called.

SEE ALSO fgetc(),fputc(),fread(),fwrite(),getc(),getchar(),gets(),putc(),putchar(),puts(), C99.

MENU LIBRARIES

floor

double floor (double lower)

HEADER math.h

PURPOSE

To round the double precision value passed to lower, down to its next whole number.

RESULTIf successfulfloor()returns a double value rounded down to its nearest whole number, otherwise if the value returned by floor

()is not a double, a range error (an illegal return value) will occur.

Or if the value is too large to fit inside a double, floor()returns +or - HUGE_VAL, in either case errnois set to ERANGE.

If the value is too smallfloor()returns 0.0.


NOTESIf the value contained within lower is not a double adomain error (an illegal argument) will occur, and the global integer

errnoset to EDOM.

SEE ALSO ceil(),fabs(),fmod().

MENU LIBRARIES

fmod

double fmod (double first, double second)

HEADER math.h




20/63

PURPOSE

To calculate the remainder offirstdivided bysecond.

RESULTIf successfulfmod()returns a positive double precision value that is less than the value of second, otherwise if the

value returned byfmod()is not a double, a range error (an illegal return value) will occur.

Or if the value is too large to fit inside a double, fmod()returns +or - HUGE_VAL, in either case errnois set to ERANGE.

If the value is too smallfmod()returns 0.0.


NOTESIf the values of bothfirstandseconddo not contain double precision numbers, adomain error (an illegal argument) will

occur, and the global integer errnoset to EDOM.

If the value ofsecondisZERO, whether a domain error occurs orfmod()returns 0.0 is implementation defined.

SEE ALSO ceil(),fabs(),floor().

MENU LIBRARIES

fopen

FILE *fopen (const char *file_name, const char *mode)

HEADER stdio.h

PURPOSE

To open the file, whose name is pointed to byfile_name, where modepoints to the type of access allowed.

RESULTIf successful,fopen()returns a pointer to the opened file. Otherwise it returns the macro NULL

(a NULL pointer).

NOTESUnless the length of *file_nameis implementation defined, FILENAME_MAX will be the recommended size of the array.

The macro FOPEN_MAXdetermines the number of files that a program may have open at the same time, under MSDOS

this will be at least eight.

Since three are always assigned tostdin(standard input),stdout(standard output), andstderr (standard error), that leaves five.

However, these three can if necessary be reassigned usingfreopen().


Or vice versa, without first calling eitherfflush(),fseek(),fsetpos(),orrewind().

Unless EOFwas the last character read byfread().

The parameter pointed to by mode must contain one of the following values:

"a" Open a text file for writing, create one if it does not already exist, append to the bottom of the file.




21/63

"a+" Open a text file for reading and writing, create one if it does not already exist, append to the bottom of the file.

"ab" Open a binary file for writing, create one if it does not already exist, append to the bottom of a file.

"ab+" Open a binary file for reading and writing, create one if it does not already exist, append to the bottom of the file.

"r" Open a text file, if it already exists for reading

"r+" Open a text file, for reading and writing, if it already exists erase the contents.

"rb" Open a binary file, if it already exists for reading.

"rb+" Open a binary file, for reading and writing, if it already exists erase the contents.

"w" Open a text file for writing, if it already exists erase the contents, otherwise create one.

"w+" Open a text file for reading and writing, if it already exists erase the contents.

"wb" Open a binary file for writing, if it already exists erase the contents.

"wb+" Open a binary file for reading and writing, if it already exists erase the contents.

SEE ALSO fclose(),ftell(),fgetpos(), C99.

MENU LIBRARIES

fprintf

int fprintf (FILE *file_pointer, const char *format, [argument], ...)

HEADER stdio.h

PURPOSETo write a series of alphanumeric or printable characters to the file pointed to by file_pointer.

Whereformatpoints to the type of alphanumeric or printable character or characters, which will be contained in argument,




22/63

and'...'indicates a variable number of arguments.

RESULTIf successful,fprintfreturns the number of characters that have been written to the file, otherwise a negative value is returned.

A minimum of509characters can be written at any one time.

NOTES

The rules that apply to *formatare the same as forprintf().

SEE ALSO fscanf(),scanf(),sprintf(),sscanf(), vfprintf(), vprintf(), vsprintf()C99

MENU LIBRARIES

fputc

int fputc (int ch, FILE *file_pointer)

HEADER stdio.h

PURPOSE

To write a character to the file pointed to byfile_pointer, and increment its file position indicator.

RESULT

If successful,fputc()returns a positive value corresponding to the character written, otherwise it returns EOF.

NOTESThis function performs the same action asputc().

However,fputc()is more likely to be a function, not a macro.

Useferror()to check whether an error has occurred.

The value passed to chis converted byfputc()into an unsigned char.

If no file position indicator exists, the character is appended to the end of the file.

SEE ALSO fgetc(),fgets(),fputs(),getc(),getchar(),gets(),putchar(),puts(), ungetc().

MENU LIBRARIES

fputs

int fputs (const char *string, FILE *file_pointer)

HEADER stdio.h

PURPOSE

To write the character array pointed to bystring, into the file pointed to byfile_pointer.

RESULT

If successful,fputs() returns a positive value. Otherwise it returns EOF.




23/63

NOTES

An '\n' character at the end of the string will not be written to the file.

SEE ALSO fgetc(),fgets(),fputc(),getc(),getchar(),gets(),putc(),putchar(),puts(), ungetc(), C99.

MENU LIBRARIES

fread

size_tfread (void *buffer, size_t width, size_t count, FILE *file_pointer)

HEADER stdio.h

PURPOSETo read a group or groups of variables from a file pointed to byfile_pointer, into the array pointed to by buffer.

Where countis the number of groups is to be read, and widththeir length in bytes.

RESULT

If successful,fread()returns the number of groups read, and increments the file position indicator, otherwise it returns ZERO.

NOTES

If the file pointed to byfile_pointeris in text mode, all carriage return line feed characters will be replaced by single linefeed characters.

If the file has been opened for read/write, a read may not be followed by a write, or vice versa, without first calling either

fflush(),fseek(),fsetpos(),or rewind().


SEE ALSO fwrite(),fgetpos(),ftell(), C99.

MENU LIBRARIES

free

void free (void *memory_ptr)

HEADER stdlib.h

PURPOSE

To free an area of memory.

RESULT


NOTES

Before callingfree()the area of memory pointed to by memory_ptr, must have been assigned by calling either calloc(),malloc(),or realloc().

If the value contained in memory_ptris the valueNULL(a NULL pointer) no action occurs.




24/63

MENU LIBRARIES

freopen

FILE *freopen (const char *new_file, const char *mode, FILE *file_pointer)

HEADER stdio.h

PURPOSE

To close the file, whose name is pointed to byfile_pointer, which is then reassigned to another file.Wherenew_filepoints to the name of the new file, and modethe file access mode.

RESULTIf successful,freopen()returns the address of the new file, otherwise it returns the macro NULL

(a NULL pointer).

NOTESUnless the length of *new_fileis implementation defined,FILENAME_MAXwill be the recommended size of the array.

Seefopen()for a complete description of *mode.

freopen()can be used to redirectstderr(standard error device),stdin(standard input device), andstdout(standard

output device), to files on disk or to other devices.

freopen()clears the error and end of file indicators, linked tofile_pointer.

SEE ALSO fclose(),fflush(),setbuf(),setvbuf(), C99.

MENU LIBRARIES

frexp

double frexp (double num, int *exp)

HEADER math.h

PURPOSE

To convert the value passed to numinto its mantissa,within the range of 0.5 to 0.999.

RESULTIf successfulfrexp()returns the mantissa of num, and stores the exponent in the integer pointed to by exp, otherwise if the

value returned byfrexp()is not a double, a range error (an illegal return value) will occur.

Or if the value is too large to fit inside a double,frexp()returns +or - HUGE_VAL, in either case errnois set to ERANGE.

If the value is too small,ornumequals ZERO,frexp()returns 0.0.


NOTESIf the values passed tofrexpare not, a double precision number and an integer, in that order.

A domain error (an illegal argument) will result, and the global integer errnoset to EDOM.

If num contains ZERO,frexp()will return ZERO, and store ZEROin *exp.




25/63

SEE ALSO exp(), ldexp(), log(),log10(), modf().

MENU LIBRARIES

fscanf

int fscanf (FILE *file_pointer, const char *format, [argument],...)

HEADER stdio.h

PURPOSETo read information from the file pointed to byfile_pointer, into the areas of memory specified by argument.

Where argument contains the addresses of those memory areas, *formatdescribes the type of alphanumeric or

printable characters contained in argument, and '... 'indicates a variable number of arguments.

RESULTIf is successful,fscanf()returns the number of groups of variables that have been read.

Otherwise it returns EOFin the case of an error,or ZEROif none were read.

To check whether the EOFcharacter has been reached, call either feof()orferror().

NOTES

Seescanf()for a complete description of *format.

SEE ALSO fprintf(),printf(),sprintf(),sscanf(), vfprintf(), vprintf(),vsprintf(), C99.

MENU LIBRARIES

fseek

int fseek (FILE *file_pointer, long int offset, int start_point)

HEADER stdio.h

PURPOSETo reset the file position indicator, within the file pointed to byfile_pointer.

Where offsetis the number of bytes that need to be added tostart_point, the current position of that indicator.

RESULT

If successful,fseek()returns ZERO. Otherwise it returns a NON ZEROvalue.

NOTES

fseek()supports random input/outputoperations, and will reset the End Of File indicator.

start_pointmust contain one of the following constants:-

SEEK_CUR - seek from the current file position

SEEK_END - seek from the End Of File




26/63

SEEK_SET - seek from the beginning of the file

SEEK_END - may not always work with binary files.

The carriage return line feed characters contained within text files will cause results to be unpredictable.

When using text files the value contained within offset, should be either 0L or returned byftell().

If ungetc()has been called immediately beforefseek()any action it has caused will be ignored.


Or vice versa, without first calling eitherfflush(), fseek(), fsetpos(),or rewind().

SEE ALSO fgetpos(),fread(),fwrite().

MENU LIBRARIES

fsetpos

int fsetpos (FILE *file_pointer, constfpos_t*position)

HEADER stdio.h

PURPOSE

To move the file position indicator pointed to byfile_pointer, to the location pointed to by position.

RESULTIf successful,fsetpos()returns ZERO, and resets the End Of File indicator.

Otherwise it returns a NON ZEROvalue, and stores an implementation defined positive number in the global integer errno.

NOTESThe value pointed to bypositionmust be obtained by callingfgetpos(), .


Or vice versa, without first calling eitherfflush(),fseek(), fsetpos(),or rewind().

fsetpos()undoes the work of ungetc().

SEE ALSO fread(),fwrite(),ftell().

MENU LIBRARIES

ftell

long int ftell (FILE *file_pointer)

HEADER stdlib.h

PURPOSE

To obtain the location of the file position indicator pointed to byfile_pointer, in bytes from the beginning of the file.




27/63

RESULTIf successful,ftell()returns the location of the file position indicator, as an offsetin relation to the beginning of the file.

Otherwise it returns the -1L, and stores an implementation defined positive value in the global integer errno.

NOTES

When using text files the long value returned byftell(),should be used withfseek().

SEE ALSO fread(),fwrite(),fgetpos(),fsetpos(), rewind().

MENU LIBRARIES

fwrite

size_tfwrite (const void *buffer, size_t width, size_t count, FILE *file_pointer)

HEADER stdio.h

PURPOSETo increment the file position indicator and write groups of variables to the file pointed to by file_pointer, from the

character array pointed to by buffer.

Where countis the number of groups being written, and widthis the length of an individual group in bytes.

RESULTIf successfulfwrite()returns the number of groups written to the file.

In the event of an error this value will be less than count.

NOTESIf the file has been opened for read/write, a read may not be followed by a write.

Or vice versa, without first calling eitherfflush(),fseek(),fsetpos(),or rewind().


SEE ALSO fgetpos(), C99.

MENU LIBRARIES

getc

int getc (FILE *file_pointer)

HEADER stdio.h

PURPOSE

To read a character from the file pointed to byfile_pointer.

RESULTIf successful,getc()returns the numerical value of the character read, otherwise it returns EOF.




28/63

NOTESgetc()may be implemented by a macro usingfgetc().

Usefeof()orferror()to check whether the End Of the File has been reached or an error has occurred.


Or vice versa, without first calling eitherfflush(),fseek(),fsetpos(),orrewind().

Unless EOFwas the last character read byfread()

SEE ALSO fgets(),fputc(),fputs(),getchar(),gets(),putc(),putchar(),puts(), ungetc().

MENU LIBRARIES

getchar

int getchar (void)

HEADER stdio.h

PURPOSE

To read a character fromstdin(the standard input device), usually after the enter key has been pressed.

RESULT

If successful,getchar()returns the numerical value of the character read, otherwise it returns EOF.

NOTESgetchar()does not display the character it has received on the screen, and may be implemented by a macro using getc().

Useferror()orfeof()to check whether an error has occurred, or the End Of File has been reached.

SEE ALSO fgetc(),fgets(),fputc(),fputs(),getc(),gets(),putc(),putchar(),puts(), ungetc().

MENU LIBRARIES

getenv

char *getenv (const char *env_name)

HEADER stdlib.h

PURPOSETo obtain specific information relating to file directories, contained in the environment list provided by the host

environment, whose entry title matches the string pointed to by env_name.

RESULT

If successfulgetenv()returns a pointer to the environment list entry, otherwise it returns the macro NULL(a NULL pointer).

NOTESThe string pointed to by env_namemay be overwritten the next timegetenv()is called.



SEE ALSO i () i () ()


29/63

SEE ALSO atexit(), exit(),system().

MENU LIBRARIES

gets

char *gets (char *string)

HEADER stdio.h

PURPOSE

To read a string fromstdin(the standard input device), into the character array pointed to by string.

RESULTIf successful,gets()returns a pointer to the character array.

Otherwise it will return the macro NULL(a NULL pointer), when an error has occurred or the EOFcharacter has

been received.

NOTESgets()will read the string until it receives either an '\n', or EOFcharacter, when that happens the array is terminated by an '\0'.

For that reason it is not recommended that you use this function with INTERNETprograms, usefgets()instead.

Usefeof()orferror()to check whether the EOFcharacter has been received.

SEE ALSO fgetc(),fputc(),fputs(),getc(),getchar(),putc(),putchar(),puts(), ungetc().

MENU LIBRARIES

gmtime

struct tm *gmtime (const time_t *num_seconds)

HEADER time.h

PURPOSETo convert the calendar time pointed to by num_seconds, into Coordinated Universal Time(UTC).

This information is then stored within a tm structure.

RESULT

If successfulgmtime()returns a pointer to a tm structure, otherwise it returns the macro NULL(a NULL pointer).

NOTESTo initialise num_seconds, the function time()must be called.

When using either MSDOSor OS/2, dates before 1980 may causegmtime()to return NULL.

Each time asctime(), ctime(), gmtime(), orlocaltime()is called, information contained within the tm structuremay

be overwritten.

The object time_tstores time asan implementation defined variable.

SEE ALSO clock(), difftime(), time()




30/63

MENU LIBRARIES

isalnum

int isalnum (int letter_number)

HEADER ctype.h

PURPOSE

To check whether the value passed toletter_numberis alphanumeric.

RESULT

If successful, isalnum()returns a NON ZEROvalue, otherwise it returns ZERO.

SEE ALSO isalpha(), iscntrl(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(),

isupper(), isxdigit(), C99.

MENU LIBRARIES

isalpha

int isalpha (int letter)

HEADER ctype.h

PURPOSETo check whether the value passed to letter is alphabetic, e.g. an implementation defined character, that is neither a

control character, a digit, a punctuation character, or a space..

RESULT

If successful,isalpha()returns a NON ZEROvalue, otherwise it returns ZERO.

SEE ALSO isalnum(),iscntrl(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(),


MENU LIBRARIES

iscntrl

int iscntrl (int control_delete)

HEADER ctype.h

PURPOSE



To check whether the value passed to t l d l t is either a control character (e g an implementation defined character


31/63

To check whether the value passed to control_delete, is either a control character (e.g an implementation defined character

that is not printable) or the delete character.

RESULT

If successful, iscntrl()returns a NON ZEROvalue, otherwise it returns ZERO.

SEE ALSO isalnum(), isalpha(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(),


MENU LIBRARIES

isdigit

int isdigit (int num)

HEADER ctype.h

PURPOSE

To check whether the value passed to numis a digit between 0and 9.

RESULT

If successful, isdigit()returns a NON ZEROvalue, otherwise it returns ZERO.

SEE ALSO isalnum(), isalpha(), iscntrl(), isgraph(), islower(), isprint(), ispunct(), isspace(),


MENU LIBRARIES

isgraph

int isgraph (int print)

HEADER ctype.h

PURPOSETo check whether the value passed toprint, is any printable character (e.g. an implementation defined character which can

be displayed) other than a space.

RESULT

If successful,isgraph()returns a NON ZEROvalue, otherwise it returns ZERO.

SEE ALSO isalnum(), isalpha(), iscntrl(), isdigit(), islower(), isprint(), ispunct(), isspace(),


MENU LIBRARIES

islowerfile:///G|/learning/Books%20Computer/Ultimate%20C%20Material/A%2...ctionary%20of%20ANSI%20Standard%20C%20Function%20Definitions.htm (31 of 63) [21-06-2008 18:24:36]



32/63

int islower (int ch)

HEADER ctype.h

PURPOSE

To check, when using the 'C 'locale, whether the value passed to chis a lower case letter.

RESULT

If successful,islower()returns a NON ZEROvalue, otherwise it returns ZERO.

SEE ALSO isalnum(), isalpha(), iscntrl(), isdigit(), isgraph(), ispunct(), isspace(),

isupper(), isxdigit(),C99.

MENU LIBRARIES

isprint

int isprint (int print)

HEADER ctype.h

PURPOSETo check whether the value passed toprint, is a printable character (e.g an implementation defined character that can

be displayed) or a space.

RESULT

If successful, isprint()returns a NON ZEROvalue, otherwise it returns ZERO.

SEE ALSO isalnum(), isalpha(), iscntrl(), isdigit(), isgraph(), islower(), ispunct(), isspace(),


MENU LIBRARIES

ispunct

int ispunct (int comma)

HEADER ctype.h

PURPOSETo check whether the value passed tocommais a punctuation character.

In other wordsANYprintable character which is neither alphanumeric, a control character, nor a space.

RESULT

If successful,ispunct()returns a NON ZEROvalue, otherwise it returns ZERO.

SEE ALSO isalnum(), isalpha(), iscntrl(), isdigit(), isgraph(), islower(),isprint(), isspace(),



isupper() isxdigit() C99


33/63


MENU LIBRARIES

isspace

int isspace (int space)

HEADER ctype.h

PURPOSETo check, when using the'C 'locale, whether the value passed tospaceis either:-

' a space character

'\t' a horizontal tab

'\v' a vertical tab

'\f' a form feed

'\r' a carriage return

'\n' a new linecharacter

RESULT

If successful, isspace()returns a NON ZEROvalue, otherwise it returns ZERO.

SEE ALSO isalnum(), isalpha(), iscntrl(), isdigit(), isgraph(), islower(), isprint(), ispunct()isupper(), isxdigit(), C99

MENU LIBRARIES

isupper



int isupper (int ch)


34/63

int isupper (int ch)

HEADER ctype.h

PURPOSE

To check whether the value passed to chis an upper case character.

RESULT

If successful,isupper()returns a NON ZEROvalue, otherwise it returns ZERO.

SEE ALSO isalnum(), isalpha(), iscntrl(), isdigit(), isgraph(), islower(), ispunct(),

isspace(), isxdigit(), C99.

MENU LIBRARIES

isxdigit

int isxdigit (int hex)

HEADER ctype.h

PURPOSETo check whether the value passed to hexis either a hexadecimal digit, a decimal digit, or a letter between the ranges 'A' -

'F', and 'a' - 'f'.

RESULT

If successful, isxdigit()returns a NON ZEROvalue, otherwise it returns ZERO.

SEE ALSO isalnum(), isalpha(), iscntrl(), isdigit(), isgraph(), islower(), isprint(),

ispunct(), isupper(), C99.

MENU LIBRARIES

labs

long int labs (long int num)

HEADER stdlib.h

PURPOSE

To calculate the absolute (e.g. positive ) value of num.

RESULT

If successfullabs()returns the absolute value of num, otherwise the value returned is implementation defined.

NOTES

The absolute value of a number can only be positive.



35/63


ldiv t


36/63

ldiv_t

SEE ALSO div().

MENU LIBRARIES

localeconv

struct lconv *localeconv (void)

HEADER locale.h

PURPOSE

To initialise the structurelconv, with the numerical and monetary values of the current locale.

RESULT

localeconv()returns a pointer to the structure lconv.

NOTESlocaleconv()is called beforesetlocale(), even thoughsetlocale()can change the contents of the structure.

The structurelconvcontains the following:

char *decimal point The decimal point character

char *thousands_sep The character used to denote thousands

char *grouping The length of each group of numbers

char *int_curr_symbol The International currency symbol consisting of 3 letters

char *currency_symbol The local currency symbol used by that particular country or region

char *mon_decimal_point The character used to represent the decimal point, when used with money

char*mon_thousands_sep

The character used to separate thousands, when used with money

char *mon_grouping The length of each group of numbers when used with money




37/63

char *positive_sign The plus sign

char *negative_sign The minus sign

char int_frac_digitsHow many numbers are to be displayed after the decimal point, when used withinternational currency

char frac_digits How many numbers are to be displayed after the decimal point, when used withlocal currency.

char p_cs_precedes Whether the currrency symbol comes before (1), or (0) after a sum of money.

char p_sep_by_spaceWhether the currency symbol is (1), separated by a space from a sum of money(otherwise 0).

char n_cs_precedesWhether the currency symbol comes before (1) or (0) after a negative sum ofmoney.

char n_sep_by_spaceWhether the currency symbol is separated by a space (1), from a negative sum ofmoney (otherwise 0).

char p_sign_posn The position of the plus sign when used with currency.

char n_sign_posn The position of the minus sign when used with currency.

Bothp_sign_posn andn_sign_posnuse the following values:

0 Brackets surround the entire sum of money.

1 The sign is in front of both currency symbol and money.

2 The sign is behind both currency symbol and money.

3 The sign is in front of the currency symbol, wherever it appears.




38/63

4 The sign is behind the currency symbol, wherever it appears.

If any of the structure members contain the value CHAR_MAXthey are not available in thelocalebeing used.

SEE ALSO mblen(), mbstowcs(), mbtowc(), wcstombs(), wctomb().

MENU LIBRARIES

localtime

struct tm *localtime (const time_t *num_seconds)

HEADER time.h

PURPOSETo convert the calendar time pointed to by num_secondsinto the local time zone, this information is stored within a

tm structure.

RESULT

If successful localtime()returns a pointer to the tm structure, otherwise the value returned is implementation defined.

NOTESLocal time effects the time zone, and daylight savings time members of the tm structure.

To initialise the pointer num_seconds, the function time() must be called.

Each time ctime(),gmtime(), or localtime()is called, information within the tm structuremay be overwritten.

The object time_tstores time as an implementation defined variable.


MENU LIBRARIES

logdouble log (double num)

HEADER math.h

PURPOSE

To calculate the natural logarithm of the value passed to num.

RESULTIf successful log() returns the natural logarithm of num, otherwise if the value returned by log()is not a double, a range

error (an illegal return value) will occur.

Or if the value is too large to fit inside a double,log()returns +or - HUGE_VAL, in either case errnois set to ERANGE.If the value is too small log()returns 0.0.




NOTES


39/63

NOTESIf the value passed to numis not a double precision number or is negative, a domain error (an illegal argument) will occur,

and the global integer errnois set to EDOM.

SEE ALSO log10, C99.

MENU LIBRARIES

log10

double log10 (double num)

HEADER math.h

PURPOSE

To calculate the base 10 logarithm for num.

RESULTIf successful log10()returns the base 10 logarithm of the value passed to num, otherwise if the value returned bylog10()is

not a double, a range error (an illegal return value) will occur.

Or if the value is too large to fit inside a double, log10()returns +or - HUGE_VAL, in either case errnois set to ERANGE.

If the value is too smalllog10()returns 0.0.When a domain error occurs, an implementation defined value is returned.

NOTESIf the value passed to numis not a double precision number, or is negative, a domain error (an illegal argument) will occur,

and the global integer errnois set to EDOM.

SEE ALSO log().

MENU LIBRARIES

longjmp

void longjmp (jmp_buf stackinfo, int ret_value)

HEADER setjmp.h

PURPOSETo enable the line of execution within a program to jump backwards from one function into another. Where stackinfo

contains the information used to reset the stack, andret_valuethe value returned bysetjump()to the function which

originally called it.

RESULT


NOTES



In order to initialisestackinfo, setjmp()must be called before longjmp().


40/63

If after longjmp()has finished, the program is unable to move back to the statement following the call to setjmp()that

definedstackinfo, errors may occur.

Functions which control error handling, and program recovery, often use setjump(), and longjump().

MENU LIBRARIES

main

int main (void) or (int argc, char *argv[])

HEADER stdio.h

PURPOSETo provide a start point within a'C' program, all other functions are called from inside main().

Information passed to the program through main() must use the following parameters:

argcthe number of items of information that are to be passed.

*argv[]a pointer to an array of character pointers, normally the operating systems command line.

RESULT

main() can return the values EXIT_FAILUREor EXIT_SUCCESS once they have been passed by exit().

NOTES

main() must NOTbe called recursively, this means it must not be called more than once within the program.

MENU LIBRARIES

malloc

void *malloc (size_tamount)

HEADER stdlib.h

PURPOSE

To allocate an area of memory from the heap, where amount is the memory size.

RESULTIf successful malloc()returns a generic pointer to the area of memory allocated, otherwise it returns the macro NULL(a

NULL pointer).

NOTESIf malloc()does return NULLand it remains undetected, the system may crash.

Unlike calloc(), areas of memory allocated by malloc()are not initialised to ZERO.

SEE ALSO free(), realloc().



MENU LIBRARIES


41/63

mblen

int mblen (const char *m_byte,size_tlength)

HEADER stdlib.h

PURPOSE

To calculate the number of bytes contained in a multibyte character, where lengthis the number of bytes in the array.

RESULTIf successful mblen()returns the exact number of bytes used to create the multibyte character in the string pointed to

by m_byte.

Otherwise it returns -1in the case of an error during conversion where mblen()stores EILSEQinerrno.

Or -2 if mblen()processed an incomplete multibyte character.

If *m_byteis a NULLpointermblen()may return either ZEROor NON ZERO depending on how the multibyte character

was encoded.

NOTESlengthcannot contain a value greater than MB_CUR_MAX.

mblen()is effected by changes to the LC_CTYPEcategory of the current locale.

SEE ALSO localeconv(),setlocale(), mbstowcs(), mbtowc(), wcstombs(), wctomb().

MENU LIBRARIES

mbstowcs

mbstowcs (wchar_t*w_string, const char *m_string,size_tlength)

HEADER stdlib.h

PURPOSETo convert a series of multibyte characters contained in *m_stringinto wide characters, where lengthis the number of

bytes within that array, and *w_stringthe array where they are stored.

RESULTIf successful mbstowcs()returns the number of characters converted, not including '\n', otherwise it returns -1.

If *m_stringcontains a NULLpointer,mbstowcs()may return either ZEROor NON ZERO, depending on how the

multibyte character was encoded.

NOTESmbstowcs() terminates, either afterlength number of characters have been converted, or it reaches '\n'.

lengthcannot contain a value greater than MB_CUR_MAX.

wcstombs()is effected by changes to the LC_CTYPEcategory of the current locale.

SEE ALSO localeconv(),setlocale(), mblen(), mbtowc(), wcstombs(), wctomb().




42/63

MENU LIBRARIES

mbtowc

int mbtowc (wchar_t* w_ch, const char *m_byte,size_tlength)

HEADER stdlib.h

PURPOSETo convert the multibyte character pointed to by m_byteinto a wide character, whose lengthis the number of bytes within

the array.

RESULTIf successful mbtowc()returns the exact number of bytes used to create the wide character and the value of that character

is stored in * w_ch,

Otherwise it returns -1in the case of an error during conversion where mbtowc()stores EILSEQinerrno.

Or -2 if mbtowc()processed an incomplete multibyte character.

If *m_byteis a NULLpointermbtowc()may return either ZEROor NON ZERO depending on how the multibyte

character was encoded.

NOTES

lengthcannot contain a value greater than MB_CUR_MAX.mbtowc()is effected by changes to the LC_CTYPEcategory of the current locale.

SEE ALSO localeconv(),setlocale(),mblen(), mbstowcs(), wcstombs(), wctomb().

MENU LIBRARIES

memchr

void *memchr(const void *string, int ch,size_tcount)

HEADER string.h

PURPOSE

To search the character array pointed to bystringfor the character passed to ch, where countis the length of that array.

RESULTIf successful, memchr() returns a generic pointer to the first array element containing ch, otherwise it returns the macro

NULL(a NULL pointer).

NOTES

memchr()convertschinto an unsigned char.

SEE ALSO memcmp(), memcpy(), memmove(), memset(),strchr(),strcspn(),strpbrk(),

strrchr(),strspn(),strstr().



MENU LIBRARIES


43/63

memcmp

int memcmp (const void *area1, const void *area2,size_twidth)

HEADER string.h

PURPOSETo compare the area of memory pointed to by area1, with the area of memory pointed to by area2.

Both of which are at least widthnumber of characters long.

RESULT

If successfulmemcmp()returns one of the following values:

Less than ZERO If *area1 is less than *area2

ZERO If *area1 is equal to *area2

Greater than ZEROIf *area1 is greater than*area2

NOTES

The characters within the two areas of memory are treated as unsigned char by memcmp().

SEE ALSO memchr(), memcpy(), memmove(), memset(),strcmp(),strncmp(),strcoll().

MENU LIBRARIES

memcpy

void *memcpy(void *to, const void *from,size_twidth)

HEADER string.h

PURPOSETo copy information from the area of memory pointed to byfrom, into the area of memory pointed to by to.

Where widthcontains the length of the information in bytes.

RESULTIf successfulmemcpy()returns a generic pointer containing the destination address.



NOTES

U lik () if f l i f i b i b f i i i d


44/63

Unlike memmove(), if areas of memory overlap, information may be overwritten before it is copied.

SEE ALSO memchr(), memcmp(), memset(),strcpy(),strncpy().

MENU LIBRARIES

memmove

void *memmove (void *to, const void *from,size_twidth)

HEADER string.h

PURPOSETo copy information from the area of memory pointed to byfrom, into the area of memory pointed to by to.

Where widthcontains the length of the information in bytes.

RESULT

If successful memmove()returns a generic pointer containing the destination address.

NOTES

Unlike memcpy(), memmove()will , if areas of memory overlap, copy information before it is overwritten.

SEE ALSO memchr(), memcmp(), memset(),strcpy(),strncpy().

MENU LIBRARIES

memset

void *memset (void *buffer, int ch,size_tcount)

HEADER string.h

PURPOSE

To copy the low order byte of the value passed to ch, into countnumber of elements of the array pointed to by buffer.

RESULT

If successful, memset()returns a generic pointer containing the address of *buffer.

NOTESOne of the common uses of memset(), is to initialise a region of memory to a known value.

memset()convertschto an unsigned char.

SEE ALSO memchr(), memcmp(), memcpy(), memmove().

MENU LIBRARIES



mktime


45/63

time_t mktime (struct tm *local)

HEADER time.h

PURPOSE

To convert the local time contained within a tm structureinto calendar time.

RESULT

If successful, mktime()returns the calendar time as a variable of type time_t.Otherwise it returns (time_t)-1.

NOTESTo initialise the tm structure, localtime()must be called first.

The tm_wday and tm_ydaymembers of the tm structureare changed by this function.

When using either MSDOSor OS/2, dates before 1980 may cause mktime()to return (time_t)-1.

The object time_tstores time as an implementation defined variable.


MENU LIBRARIES

modf

double modf (double num, double *whole)

HEADER math.h

PURPOSE

To convert the value passed to numinto its whole number and fractional component parts.

RESULT

If successful modf()returns the signed fractional component of num, placing its whole number component into thedouble pointed to by whole, otherwise if the value returned by modf()is not a double, a range error (an illegal return value)

will occur.

Or if the value is too large to fit inside a double, modf()returns +or - HUGE_VAL, in either case errnois set to ERANGE.

If the value is too small modf()returns 0.0.


NOTESIf the values passed to modf()are not double precision numbers, a domain error (an illegal argument) will occur setting

the global integer errnoto EDOM.

SEE ALSO frexp(), ldexp().

MENU LIBRARIES



offsetof


46/63

size_toffsetof (structure_name, structure_member)

HEADER stddef.h

PURPOSE

A macro which measures the distance between structure_name, and structure_member.

RESULT

offsetof() is a macro which expands to an integral constant expression of typesize_t,containing the number of bytes

between the start point ofstructure_name, and the beginning ofstructure_member.

NOTES

Ifstructure_membercontains a bit-field, its behaviour is implementation defined.

SEE ALSO sizeof

MENU LIBRARIES

perror

void perror (const char *string)

HEADER stdio.h

PURPOSE

To send error messages tostderr(the standard error device).

RESULT


NOTES

Unlessstringcontains the value NULL, or the character pointed to bystringis '\0'.An appropriate error message will be displayed, consisting of text obtained from the character array *string, followed by ':',

and whatever error message is linked to the global integer errno

SEE ALSO clearerr(),feof(),ferror(),strerror().

MENU LIBRARIES

pow

double pow (double base, double exp)

HEADER math.h



PURPOSETo calculate the value of base raised to the power of exp


47/63

To calculate the value of baseraised to the power of exp.

RESULTIf successfulpow()returns the value of base raised to the power of exp, otherwise if the value returned bypow()is not a

double, a range error (an illegal return value) will occur.

Or if the value is too large to fit inside a double,pow()returns +or - HUGE_VAL, in either case errnois set to ERANGE.

If the value is too smallpow()returns 0.0.

NOTESIf the values passed topow()are not double precision numbers.

Or if the value of baseis ZERO, and the value of expis less than or equal to ZERO.Orbasecontains a negative value, and expis not an integer.

Then a domain error (an illegal argument) will occur, and the global integer errnoset to EDOM.


Values greater than 2 to the power of 64 cannot be computed by pow().

SEE ALSO exp(), log(), log10(),sqrt(),C99.

MENU LIBRARIES

printf

int printf (const char *format, [argument],...)

HEADER stdio.h

PURPOSETo format and send printable characters to the standard output device (stdout), usually the video screen.

Where *formatdefines the type of printable character contained in argument, which can be optional, and '...' indicates a

flexible number of arguments.

RESULTIf successfulprintfreturns the number of characters sent tostdout.

Otherwise it returns a negative value.

NOTES*formatcontains the text to be printed, optionally it can contain format tags that are substituted by the values specified

in argument.

These tags must be equal in number to the arguments used.

*format may contain some or all of the following information in this order:

% [MODIFIER] [WIDTH] [.PRECISION] [TAG] TEXT

MODIFIER Specifies the type of character conversion or alignment




48/63

WIDTH Minimum field width

PRECISION Minimum number of digits to be displayed

TAG Convert data into characters

TEXT Character to be displayed, printed or stored

The following are a list of format identifiers which can be used withprintf, and the variable types they display:

%c A single unsigned character

%d A signed decimal integer

%i A signed decimal integer

%e A floating point variable (exponent)

%E A floating point variable (exponent)

%f A floating point variable

%F A floating point variable

%g Allows system to choose either %e or %f

%G Allows system to choose either %Eor %F

%hd A signed short integer



%hi A signed short integer


49/63

%hi A signed short integer

%ho An unsigned short integer (octal)

%hn A short argument

%hu An unsigned short integer

%hx An unsigned short integer (hexadecimal lower case)

%hX An unsigned short integer (hexadecimal upper case)

%ld A signed long integer

%le A double precision variable (exponent)

%lE A double precision variable (exponent)

%lf A double precision variable

%lF A double precision variable

%lg Allows system to choose either %leor %lf

%lG

Allows system to choose either %lE or %lF

%li A signed long integer

%ln A long argument



%lo An unsigned long integer (octal)


50/63

%lo An unsigned long integer (octal)

%lu An unsigned long integer

%lx An unsigned long integer (hexadecimal lower case)

%lX An unsigned long integer (hexadecimal lower case)

%Le

A long double precision variable (exponent)

%LE

A long double precision variable (exponent)

%Lf A long double precision variable

%LF A long double precision variable

%Lg

Allows system to choose either %Le or %Lf

%LG Allows system to choose either %LEor %LF

%nThe number of characters written so far by printf()

%p A generic pointer (and its address)

%o An unsigned integer (octal)

%s A pointer to a character string



%u An unsigned decimal integer


51/63

%u An unsigned decimal integer

%x An unsigned hexadecimal (lower case)

%X An unsigned hexadecimal (upper case)

%% The % sign

#e Decimal point appears even when not needed

#f Decimal point appears even when not needed

#g Decimal point appears even when not needed

#x Hexadecimal with ox prefix

\a Alert

\b Back space

\f Form feed

\n New line

\r Carriage return

\t Tab

\v Vertical tab



\ooo Up to three digit octal number


52/63

\ooo Up to three digit octal number

SEE ALSO fscanf(),fprintf(),scanf(),sscanf(),sprintf(), C99.

MENU LIBRARIES

putc

int putc (int ch, FILE *file_pointer)

HEADER stdio.h

PURPOSETo write a character to the file pointed to byfile_pointer.

RESULTIf successfulputc()returns the numerical value of the character written to the file.

Otherwise it returns EOF.

NOTESUseferror()to check for errors.

putc()may also be implemented by a macro usingfputc().

SEE ALSO fgetc(),fgets(),fputs(),getc(),getchar(),gets(),putchar(),puts(), ungetc().

MENU LIBRARIES

putchar

int putchar (int ch)

HEADER stdio.h

PURPOSETo write a character tostdout(the standard output device), usually the video screen.

RESULTIf successful,putchar() returns the numerical value of the value written, otherwise it returns EOF.

NOTESUseferror()to check for errors,putchar() may also be implemented by a macro usingfputc().

SEE ALSO fgetc(),fgets(),fputc(),fputs(),getc(),getchar(),gets(),putc(),puts(), ungetc().

MENU LIBRARIES



puts


53/63

p

int puts (const char *string)

HEADER stdio.h

PURPOSETo write a string tostdout(the standard output device), usually the video screen.

RESULTIf sucessfulputs()returns a positive value, otherwise it returns EOF.

NOTESUseferror()to check for errors.

Unlikefputs(),puts() appends a new line to the output string.

In other words wheneverputs()encounters a '\0' character it replaces it with '\n'.

SEE ALSO fgetc(),fgets(),,fputc(),getc(),getchar(),gets(),putc(),putchar(),ungetc().

MENU LIBRARIES

qsort

void qsort (void *buffer,size_tlength, size_t width,

int (*compare)( const void *key, const void *elem)

Documents

A Dictionary of ANSI Standard C Function Definitions