4. LIBRARY

4.1 INTRODUCTION

4.1.1 Definitions of terms

A string is a contiguous sequence of characters terminated by and including the first null character. It is represented by a pointer to its initial (lowest addressed) character and its length is the number of characters preceding the null character.

A letter is a printing character in the execution character set corresponding to any of the 52 required lower-case and upper-case letters in the source character set, listed in $2.2.1.

The decimal-point character is the character used by functions that convert floating-point numbers to or from character sequences to denote the beginning of the fractional part of such character sequences./80/ It is represented in the text and examples by a period, but may be changed by the setlocale function.

Forward references: character handling ($4.3), the setlocale function ($4.4.1.1).

4.1.2 Standard headers

Each library function is declared in a header ,/81/ whose contents are made available by the #include preprocessing directive. The header declares a set of related functions, plus any necessary types and additional macros needed to facilitate their use. Each header declares and defines only those identifiers listed in its associated section. All external identifiers declared in any of the headers are reserved, whether or not the associated header is included. All external identifiers that begin with an underscore are reserved. All other identifiers that begin with an underscore and either an upper-case letter or another underscore are reserved. If the program defines an external identifier with the same name as a reserved external identifier, even in a semantically equivalent form, the behavior is undefined./82/

The standard headers are

<assert.h> <locale.h> <stddef.h>

<ctype.h> <math.h> <stdio.h>

<errno.h> <setjmp.h> <stdlib.h>

<float.h> <signal.h> <string.h>

<limits.h> <stdarg.h> <time.h>

If a file with the same name as one of the above < and > delimited sequences, not provided as part of the implementation, is placed in any of the standard places for a source file to be included, the behavior is undefined.

Headers may be included in any order; each may be included more than once in a given scope, with no effect different from being included only once, except that the effect of including <assert.h> depends on the definition of NDEBUG . If used, a header shall be included outside of any external declaration or definition, and it shall first be included before the first reference to any of the functions or objects it declares, or to any of the types or macros it defines. Furthermore, the program shall not have any macros with names lexically identical to keywords currently defined prior to the inclusion.

Forward references: diagnostics ($4.2).

4.1.3 Errors <errno.h>

The header <errno.h> defines several macros, all relating to the reporting of error conditions.

The macros are

EDOM

ERANGE

which expand to distinct nonzero integral constant expressions; and

errno

which expands to a modifiable lvalue/83/ that has type int , the value of which is set to a positive error number by several library functions. It is unspecified whether errno is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual object, or a program defines an external identifier with the name errno , the behavior is undefined.

The value of errno is zero at program startup, but is never set to zero by any library function./84/ The value of errno may be set to nonzero by a library function call whether or not there is an error, provided the use of errno is not documented in the description of the function in the Standard.

Additional macro definitions, beginning with E and a digit or E and an upper-case letter,/85/ may also be specified by the implementation.

4.1.4 Limits <float.h> and <limits.h>

The headers <float.h> and <limits.h> define several macros that expand to various limits and parameters.

The macros, their meanings, and their minimum magnitudes are listed in $2.2.4.2.

4.1.5 Common definitions <stddef.h>

The following types and macros are defined in the standard header <stddef.h>. Some are also defined in other headers, as noted in their respective sections.

The types are

ptrdiff_t

which is the signed integral type of the result of subtracting two pointers;

size_t

which is the unsigned integral type of the result of the sizeof operator; and

wchar_t

which is an integral type whose range of values can represent distinct codes for all members of the largest extended character set specified among the supported locales; the null character shall have the code value zero and each member of the basic character set defined in $2.2.1 shall have a code value equal to its value when used as the lone character in an integer character constant.

The macros are

NULL

which expands to an implementation-defined null pointer constant; and

offsetof( type, member-designator)

which expands to an integral constant expression that has type size_t , the value of which is the offset in bytes, to the structure member (designated by member-designator ), from the beginning of its structure (designated by type ). The member-designator shall be such that given

static type t;

then the expression &(t. member-designator ) evaluates to an address constant. (If the specified member is a bit-field, the behavior is undefined.)

Forward references: localization ($4.4).

4.1.6 Use of library functions

Each of the following statements applies unless explicitly stated otherwise in the detailed descriptions that follow. If an argument to a function has an invalid value (such as a value outside the domain of the function, or a pointer outside the address space of the program, or a null pointer), the behavior is undefined. Any function declared in a header may be implemented as a macro defined in the header, so a library function should not be declared explicitly if its header is included. Any macro definition of a function can be suppressed locally by enclosing the name of the function in parentheses, because the name is then not followed by the left parenthesis that indicates expansion of a macro function name. For the same syntactic reason, it is permitted to take the address of a library function even if it is also defined as a macro./86/ The use of #undef to remove any macro definition will also ensure that an actual function is referred to. Any invocation of a library function that is implemented as a macro will expand to code that evaluates each of its arguments exactly once, fully protected by parentheses where necessary, so it is generally safe to use arbitrary expressions as arguments. Likewise, those function-like macros described in the following sections may be invoked in an expression anywhere a function with a compatible return type could be called./87/

Provided that a library function can be declared without reference to any type defined in a header, it is also permissible to declare the function, either explicitly or implicitly, and use it without including its associated header. If a function that accepts a variable number of arguments is not declared (explicitly or by including its associated header), the behavior is undefined.

Examples

The function atoi may be used in any of several ways:

* by use of its associated header (possibly generating a macro expansion)

#include <stdlib.h>

const char *str;

/*...*/

i = atoi(str);

* by use of its associated header (assuredly generating a true function reference)

#include <stdlib.h>

#undef atoi

const char *str;

/*...*/

i = atoi(str);

#include <stdlib.h>

const char *str;

/*...*/

i = (atoi)(str);

* by explicit declaration

extern int atoi(const char *);

const char *str;

/*...*/

i = atoi(str);

* by implicit declaration

const char *str;

/*...*/

i = atoi(str);

4.2 DIAGNOSTICS <assert.h>

The header <assert.h> defines the assert macro and refers to another macro,

NDEBUG

which is not defined by <assert.h>. If NDEBUG is defined as a macro name at the point in the source file where <assert.h> is included, the assert macro is defined simply as

#define assert(ignore) ((void)0)

The assert macro shall be implemented as a macro, not as an actual function. If the macro definition is suppressed in order to access an actual function, the behavior is undefined.

4.2.1 Program diagnostics

4.2.1.1 The assert macro

Synopsis

#include <assert.h>

void assert(int expression);

Description

The assert macro puts diagnostics into programs. When it is executed, if expression is false (that is, compares equal to 0), the assert macro writes information about the particular call that failed (including the text of the argument, the name of the source file, and the source line number EM the latter are respectively the values of the preprocessing macros __FILE__ and __LINE__ ) on the standard error file in an implementation-defined format./88/

expression , xyz , nnn It then calls the abort function.

Returns

The assert macro returns no value.

Forward references: the abort function ($4.10.4.1).

4.3 CHARACTER HANDLING <ctype.h>

The header <ctype.h> declares several functions useful for testing and mapping characters./89/ In all cases the argument is an int , the value of which shall be representable as an unsigned char or shall equal the value of the macro EOF . If the argument has any other value, the behavior is undefined.

4.3.2.1 The tolower function

Synopsis

#include <ctype.h>

int tolower(int c);

Description

The tolower function converts an upper-case letter to the corresponding lower-case letter.

Returns

If the argument is an upper-case letter, the tolower function returns the corresponding lower-case letter if there is one; otherwise the argument is returned unchanged. In the C locale, tolower maps only the characters for which isupper is true to the corresponding characters for which islower is true.

4.3.2.2 The toupper function

Synopsis

#include <ctype.h>

int toupper(int c);

Description

The toupper function converts a lower-case letter to the corresponding upper-case letter.

Returns

If the argument is a lower-case letter, the toupper function returns the corresponding upper-case letter if there is one; otherwise the argument is returned unchanged. In the C locale, toupper maps only the characters for which islower is true to the corresponding characters for which isupper is true.

4.4 LOCALIZATION <locale.h>

The header <locale.h> declares two functions, one type, and defines several macros.

The type is

struct lconv

which contains members related to the formatting of numeric values. The structure shall contain at least the following members, in any order. The semantics of the members and their normal ranges is explained in $4.4.2.1. In the C locale, the members shall have the values specified in the comments.

char *decimal_point; /* "." */

char *thousands_sep; /* "" */

char *grouping; /* "" */

char *int_curr_symbol; /* "" */

char *currency_symbol; /* "" */

char *mon_decimal_point; /* "" */

char *mon_thousands_sep; /* "" */

char *mon_grouping; /* "" */

char *positive_sign; /* "" */

char *negative_sign; /* "" */

char int_frac_digits; /* CHAR_MAX */

char frac_digits; /* CHAR_MAX */

char p_cs_precedes; /* CHAR_MAX */

char p_sep_by_space; /* CHAR_MAX */

char n_cs_precedes; /* CHAR_MAX */

char n_sep_by_space; /* CHAR_MAX */

char p_sign_posn; /* CHAR_MAX */

char n_sign_posn; /* CHAR_MAX */

The macros defined are NULL (described in $4.1.5); and

LC_ALL

LC_COLLATE

LC_CTYPE

LC_MONETARY

LC_NUMERIC

LC_TIME

which expand to distinct integral constant expressions, suitable for use as the first argument to the setlocale function. Additional macro definitions, beginning with the characters LC_ and an upper-case letter,/91/ may also be specified by the implementation.

4.4.1 Locale control

4.4.1.1 The setlocale function

Synopsis

#include <locale.h>

char *setlocale(int category, const char *locale);

Description

The setlocale function selects the appropriate portion of the program's locale as specified by the category and locale arguments. The setlocale function may be used to change or query the program's entire current locale or portions thereof. The value LC_ALL for category names the program's entire locale; the other values for category name only a portion of the program's locale. LC_COLLATE affects the behavior of the strcoll and strxfrm functions. LC_CTYPE affects the behavior of the character handling functions/92/ and the multibyte functions. LC_MONETARY affects the monetary formatting information returned by the localeconv function. LC_NUMERIC affects the decimal-point character for the formatted input/output functions and the string conversion functions, as well as the non-monetary formatting information returned by the localeconv function. LC_TIME affects the behavior of the strftime function.

A value of C for locale specifies the minimal environment for C translation; a value of for locale specifies the implementation-defined native environment. Other implementation-defined strings may be passed as the second argument to setlocale .

At program startup, the equivalent of

setlocale(LC_ALL, "C");

is executed.

The implementation shall behave as if no library function calls the setlocale function.

Returns

If a pointer to a string is given for locale and the selection can be honored, the setlocale function returns the string associated with the specified category for the new locale. If the selection cannot be honored, the setlocale function returns a null pointer and the program's locale is not changed.

A null pointer for locale causes the setlocale function to return the string associated with the category for the program's current locale; the program's locale is not changed.

The string returned by the setlocale function is such that a subsequent call with that string and its associated category will restore that part of the program's locale. The string returned shall not be modified by the program, but may be overwritten by a subsequent call to the setlocale function.

Forward references: formatted input/output functions ($4.9.6), the multibyte character functions ($4.10.7), the multibyte string functions ($4.10.8), string conversion functions ($4.10.1), the strcoll function ($4.11.4.3), the strftime function ($4.12.3.5), the strxfrm function ($4.11.4.5).

4.4.2 Numeric formatting convention inquiry

4.4.2.1 The localeconv function

Synopsis

#include <locale.h>

struct lconv *localeconv(void);

Description

The localeconv function sets the components of an object with type struct lconv with values appropriate for the formatting of numeric quantities (monetary and otherwise) according to the rules of the current locale.

The members of the structure with type char * are strings, any of which (except decimal_point ) can point to , to indicate that the value is not available in the current locale or is of zero length. The members with type char are nonnegative numbers, any of which can be CHAR_MAX to indicate that the value is not available in the current locale. The members include the following:

The decimal-point character used to format non-monetary quantities.

The character used to separate groups of digits to the left of the decimal-point character in formatted non-monetary quantities.

A string whose elements indicate the size of each group of digits in formatted non-monetary quantities.

The international currency symbol applicable to the current locale. The first three characters contain the alphabetic international currency symbol in accordance with those specified in ISO 4217 Codes for the Representation of Currency and Funds .The fourth character (immediately preceding the null character) is the character used to separate the international currency symbol from the monetary quantity.

The local currency symbol applicable to the current locale.

The decimal-point used to format monetary quantities.

The separator for groups of digits to the left of the decimal-point in formatted monetary quantities.

A string whose elements indicate the size of each group of digits in formatted monetary quantities.

The string used to indicate a nonnegative-valued formatted monetary quantity.

The string used to indicate a negative-valued formatted monetary quantity.

The number of fractional digits (those to the right of the decimal-point) to be displayed in a internationally formatted monetary quantity.

The number of fractional digits (those to the right of the decimal-point) to be displayed in a formatted monetary quantity.

Set to 1 or 0 if the currency_symbol respectively precedes or succeeds the value for a nonnegative formatted monetary quantity.

Set to 1 or 0 if the currency_symbol respectively is or is not separated by a space from the value for a nonnegative formatted monetary quantity.

Set to 1 or 0 if the currency_symbol respectively precedes or succeeds the value for a negative formatted monetary quantity.

Set to 1 or 0 if the currency_symbol respectively is or is not separated by a space from the value for a negative formatted monetary quantity.

Set to a value indicating the positioning of the positive_sign for a nonnegative formatted monetary quantity.

Set to a value indicating the positioning of the negative_sign for a negative formatted monetary quantity.

The elements of grouping and mon_grouping are interpreted according to the following: No further grouping is to be performed. The previous element is to be repeatedly used for the remainder of the digits. The value is the number of digits that comprise the current group. The next element is examined to determine the size of the next group of digits to the left of the current group.

The value of p_sign_posn and n_sign_posn is interpreted according to the following: Parentheses surround the quantity and currency_symbol . The sign string precedes the quantity and currency_symbol . The sign string succeeds the quantity and currency_symbol . The sign string immediately precedes the currency_symbol . The sign string immediately succeeds the currency_symbol .

The implementation shall behave as if no library function calls the localeconv function.

Returns

The localeconv function returns a pointer to the filled-in object. The structure pointed to by the return value shall not be modified by the program, but may be overwritten by a subsequent call to the localeconv function. In addition, calls to the setlocale function with categories LC_ALL , LC_MONETARY , or LC_NUMERIC may overwrite the contents of the structure.

Examples

The following table illustrates the rules used by four countries to format monetary quantities.

Country Positive format Negative format International format

Italy L.1.234 -L.1.234 ITL.1.234

Netherlands F 1.234,56 F -1.234,56 NLG 1.234,56

Norway kr1.234,56 kr1.234,56- NOK 1.234,56

Switzerland SFrs.1,234.56 SFrs.1,234.56C CHF 1,234.56

For these four countries, the respective values for the monetary members of the structure returned by localeconv are:

Italy Netherlands Norway Switzerland

int_curr_symbol "ITL." "NLG " "NOK " "CHF "

currency_symbol "L." "F" "kr" "SFrs."

mon_decimal_point "" "," "," "."

mon_thousands_sep "." "." "." ","

mon_grouping "\3" "\3" "\3" "\3"

positive_sign "" "" "" ""

negative_sign "-" "-" "-" "C"

int_frac_digits 0 2 2 2

frac_digits 0 2 2 2

p_cs_precedes 1 1 1 1

p_sep_by_space 0 1 0 0

n_cs_precedes 1 1 1 1

n_sep_by_space 0 1 0 0

p_sign_posn 1 1 1 1

n_sign_posn 1 4 2 2

4.5 MATHEMATICS <math.h>

The header <math.h> declares several mathematical functions and defines one macro. The functions take double-precision arguments and return double-precision values./93/ Integer arithmetic functions and conversion functions are discussed later.

The macro defined is

HUGE_VAL

which expands to a positive double expression, not necessarily representable as a float .

Forward references: integer arithmetic functions ($4.10.6), the atof function ($4.10.1.1), the strtod function ($4.10.1.4).

4.5.1 Treatment of error conditions

4.5.5.1 The pow function

Synopsis

#include <math.h>

double pow(double x, double y);

Description

The pow function computes x raised to the power y . A domain error occurs if x is negative and y is not an integer. A domain error occurs if the result cannot be represented when x is zero and y is less than or equal to zero. A range error may occur.

Returns

The pow function returns the value of x raised to the power y .

4.5.5.2 The sqrt function

Synopsis

The header <setjmp.h> defines the macro setjmp , and declares one function and one type, for bypassing the normal function call and return discipline./95/

The type declared is

jmp_buf

which is an array type suitable for holding the information needed to restore a calling environment.

It is unspecified whether setjmp is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function, or a program defines an external identifier with the name setjmp , the behavior is undefined.

4.6.1 Save calling environment

4.6.1.1 The setjmp macro

Synopsis

#include <setjmp.h>

int setjmp(jmp_buf env);

Description

The setjmp macro saves its calling environment in its jmp_buf argument for later use by the longjmp function.

Returns

If the return is from a direct invocation, the setjmp macro returns the value zero. If the return is from a call to the longjmp function, the setjmp macro returns a nonzero value.

"Environmental constraint"

An invocation of the setjmp macro shall appear only in one of the following contexts:

* the entire controlling expression of a selection or iteration statement;

* one operand of a relational or equality operator with the other operand an integral constant expression, with the resulting expression being the entire controlling expression of a selection or iteration statement;

* the operand of a unary ! operator with the resulting expression being the entire controlling expression of a selection or iteration statement; or

* the entire expression of an expression statement (possibly cast to void ).

4.6.2 Restore calling environment

4.6.2.1 The longjmp function

Synopsis

#include <setjmp.h>

void longjmp(jmp_buf env, int val);

Description

The longjmp function restores the environment saved by the most recent invocation of the setjmp macro in the same invocation of the program, with the corresponding jmp_buf argument. If there has been no such invocation, or if the function containing the invocation of the setjmp macro has terminated execution/96/ in the interim, the behavior is undefined.

All accessible objects have values as of the time longjmp was called, except that the values of objects of automatic storage duration that do not have volatile type and have been changed between the setjmp invocation and longjmp call are indeterminate.

As it bypasses the usual function call and return mechanisms, the longjmp function shall execute correctly in contexts of interrupts, signals and any of their associated functions. However, if the longjmp function is invoked from a nested signal handler (that is, from a function invoked as a result of a signal raised during the handling of another signal), the behavior is undefined.

Returns

After longjmp is completed, program execution continues as if the corresponding invocation of the setjmp macro had just returned the value specified by val . The longjmp function cannot cause the setjmp macro to return the value 0; if val is 0, the setjmp macro returns the value 1.

4.7 SIGNAL HANDLING <signal.h>

The header <signal.h> declares a type and two functions and defines several macros, for handling various signals (conditions that may be reported during program execution).

The type defined is

sig_atomic_t

which is the integral type of an object that can be accessed as an atomic entity, even in the presence of asynchronous interrupts.

The macros defined are

SIG_DFL

SIG_ERR

SIG_IGN

which expand to distinct constant expressions that have type compatible with the second argument to and the return value of the signal function, and whose value compares unequal to the address of any declarable function; and the following, each of which expands to a positive integral constant expression that is the signal number corresponding to the specified condition: abnormal termination, such as is initiated by the abort function an erroneous arithmetic operation, such as zero divide or an operation resulting in overflow detection of an invalid function image, such as an illegal instruction receipt of an interactive attention signal an invalid access to storage a termination request sent to the program

An implementation need not generate any of these signals, except as a result of explicit calls to the raise function. Additional signals and pointers to undeclarable functions, with macro definitions beginning, respectively, with the letters SIG and an upper-case letter or with SIG_ and an upper-case letter,/97/ may also be specified by the implementation. The complete set of signals, their semantics, and their default handling is implementation-defined; all signal values shall be positive.

4.7.1 Specify signal handling

4.7.1.1 The signal function

Synopsis

#include <signal.h>

void (*signal(int sig, void (*func)(int)))(int);

Description

The signal function chooses one of three ways in which receipt of the signal number sig is to be subsequently handled. If the value of func is SIG_DFL , default handling for that signal will occur. If the value of func is SIG_IGN , the signal will be ignored. Otherwise, func shall point to a function to be called when that signal occurs. Such a function is called a signal handler .

When a signal occurs, if func points to a function, first the equivalent of signal(sig, SIG_DFL); is executed or an implementation-defined blocking of the signal is performed. (If the value of sig is SIGILL, whether the reset to SIG_DFL occurs is implementation-defined.) Next the equivalent of (*func)(sig); is executed. The function func may terminate by executing a return statement or by calling the abort , exit , or longjmp function. If func executes a return statement and the value of sig was SIGFPE or any other implementation-defined value corresponding to a computational exception, the behavior is undefined. Otherwise, the program will resume execution at the point it was interrupted.

If the signal occurs other than as the result of calling the abort or raise function, the behavior is undefined if the signal handler calls any function in the standard library other than the signal function itself or refers to any object with static storage duration other than by assigning a value to a static storage duration variable of type volatile sig_atomic_t . Furthermore, if such a call to the signal function results in a SIG_ERR return, the value of errno is indeterminate.

At program startup, the equivalent of

signal(sig, SIG_IGN);

may be executed for some signals selected in an implementation-defined manner; the equivalent of

signal(sig, SIG_DFL);

is executed for all other signals defined by the implementation.

The implementation shall behave as if no library function calls the signal function.

Returns

If the request can be honored, the signal function returns the value of func for the most recent call to signal for the specified signal sig . Otherwise, a value of SIG_ERR is returned and a positive value is stored in errno .

Forward references: the abort function ($4.10.4.1).

4.7.2 Send signal

4.7.2.1 The raise function

Synopsis

#include <signal.h>

int raise(int sig);

Description

The raise function sends the signal sig to the executing program.

Returns

The raise function returns zero if successful, nonzero if unsuccessful.

4.8 VARIABLE ARGUMENTS <stdarg.h>

The va_end macro facilitates a normal return from the function whose variable argument list was referred to by the expansion of va_start that initialized the va_list ap . The va_end macro may modify ap so that it is no longer usable (without an intervening invocation of va_start ). If there is no corresponding invocation of the va_start macro, or if the va_end macro is not invoked before the return, the behavior is undefined.

Returns

The va_end macro returns no value.

Example

The function f1 gathers into an array a list of arguments that are pointers to strings (but not more than MAXARGS arguments), then passes the array as a single argument to function f2 . The number of pointers is specified by the first argument to f1 .

#include <stdarg.h>

#define MAXARGS 31

void f1(int n_ptrs, ...)

{

va_list ap;

char *array[MAXARGS];

int ptr_no = 0;

if (n_ptrs > MAXARGS)

n_ptrs = MAXARGS;

va_start(ap, n_ptrs);

while (ptr_no < n_ptrs)

array[ptr_no++] = va_arg(ap, char *);

va_end(ap);

f2(n_ptrs, array);

}

Each call to f1 shall have visible the definition of the function or a declaration such as

void f1(int, ...);

4.9 INPUT/OUTPUT <stdio.h>

4.9.1 Introduction

The header <stdio.h> declares three types, several macros, and many functions for performing input and output.

The types declared are size_t (described in $4.1.5);

FILE

which is an object type capable of recording all the information needed to control a stream, including its file position indicator, a pointer to its associated buffer, an error indicator that records whether a read/write error has occurred, and an end-of-file indicator that records whether the end of the file has been reached; and

fpos_t

which is an object type capable of recording all the information needed to specify uniquely every position within a file.

The macros are NULL (described in $4.1.5);

_IOFBF

_IOLBF

_IONBF

which expand to distinct integral constant expressions, suitable for use as the third argument to the setvbuf function;

BUFSIZ

which expands to an integral constant expression, which is the size of the buffer used by the setbuf function;

EOF

which expands to a negative integral constant expression that is returned by several functions to indicate end-of-file ,that is, no more input from a stream;

FOPEN_MAX

which expands to an integral constant expression that is the minimum number of files that the implementation guarantees can be open simultaneously;

FILENAME_MAX

which expands to an integral constant expression that is the maximum length for a file name string that the implementation guarantees can be opened;/98/

L_tmpnam

which expands to an integral constant expression that is the size of an array of char large enough to hold a temporary file name string generated by the tmpnam function;

SEEK_CUR

SEEK_END

SEEK_SET

which expand to distinct integral constant expressions, suitable for use as the third argument to the fseek function;

TMP_MAX

which expands to an integral constant expression that is the minimum number of unique file names that shall be generated by the tmpnam function;

stderr

stdin

stdout

which are expressions of type ``pointer to FILE '' that point to the FILE objects associated, respectively, with the standard error, input, and output streams.

Forward references: files ($4.9.3), the fseek function ($4.9.9.2), streams ($4.9.2), the tmpnam function ($4.9.4.4).

4.9.2 Streams

Input and output, whether to or from physical devices such as terminals and tape drives, or whether to or from files supported on structured storage devices, are mapped into logical data streams ,whose properties are more uniform than their various inputs and outputs. Two forms of mapping are supported, for text streams and for binary streams ./99/

A text stream is an ordered sequence of characters composed into lines , each line consisting of zero or more characters plus a terminating new-line character. Whether the last line requires a terminating new-line character is implementation-defined. Characters may have to be added, altered, or deleted on input and output to conform to differing conventions for representing text in the host environment. Thus, there need not be a one-to-one correspondence between the characters in a stream and those in the external representation. Data read in from a text stream will necessarily compare equal to the data that were earlier written out to that stream only if: the data consist only of printable characters and the control characters horizontal tab and new-line; no new-line character is immediately preceded by space characters; and the last character is a new-line character. Whether space characters that are written out immediately before a new-line character appear when read in is implementation-defined.

A binary stream is an ordered sequence of characters that can transparently record internal data. Data read in from a binary stream shall compare equal to the data that were earlier written out to that stream, under the same implementation. Such a stream may, however, have an implementation-defined number of null characters appended.

"Environmental limits"

An implementation shall support text files with lines containing at least 254 characters, including the terminating new-line character. The value of the macro BUFSIZ shall be at least 256.

4.9.3 Files

A stream is associated with an external file (which may be a physical device) by opening a file, which may involve creating a new file. Creating an existing file causes its former contents to be discarded, if necessary, so that it appears as if newly created. If a file can support positioning requests (such as a disk file, as opposed to a terminal), then a file position indicator /100/file pointer .associated with the stream is positioned at the start (character number zero) of the file, unless the file is opened with append mode in which case it is implementation-defined whether the file position indicator is positioned at the beginning or the end of the file. The file position indicator is maintained by subsequent reads, writes, and positioning requests, to facilitate an orderly progression through the file. All input takes place as if characters were read by successive calls to the fgetc function; all output takes place as if characters were written by successive calls to the fputc function.

Binary files are not truncated, except as defined in $4.9.5.3. Whether a write on a text stream causes the associated file to be truncated beyond that point is implementation-defined.

When a stream is unbuffered , characters are intended to appear from the source or at the destination as soon as possible. Otherwise characters may be accumulated and transmitted to or from the host environment as a block. When a stream is fully buffered ,characters are intended to be transmitted to or from the host environment as a block when a buffer is filled. When a stream is line buffered ,characters are intended to be transmitted to or from the host environment as a block when a new-line character is encountered. Furthermore, characters are intended to be transmitted as a block to the host environment when a buffer is filled, when input is requested on an unbuffered stream, or when input is requested on a line buffered stream that requires the transmission of characters from the host environment. Support for these characteristics is implementation-defined, and may be affected via the setbuf and setvbuf functions.

A file may be disassociated from its controlling stream by closing the file. Output streams are flushed (any unwritten buffer contents are transmitted to the host environment) before the stream is disassociated from the file. The value of a pointer to a FILE object is indeterminate after the associated file is closed (including the standard text streams). Whether a file of zero length (on which no characters have been written by an output stream) actually exists is implementation-defined.

The file may be subsequently reopened, by the same or another program execution, and its contents reclaimed or modified (if it can be repositioned at its start). If the main function returns to its original caller, or if the exit function is called, all open files are closed (hence all output streams are flushed) before program termination. Other paths to program termination, such as calling the abort function, need not close all files properly.

The address of the FILE object used to control a stream may be significant; a copy of a FILE object may not necessarily serve in place of the original.

At program startup, three text streams are predefined and need not be opened explicitly --- standard input (for reading conventional input), standard output (for writing conventional output), and standard error (for writing diagnostic output). When opened, the standard error stream is not fully buffered; the standard input and standard output streams are fully buffered if and only if the stream can be determined not to refer to an interactive device.

Functions that open additional (nontemporary) files require a file name ,which is a string. The rules for composing valid file names are implementation-defined. Whether the same file can be simultaneously open multiple times is also implementation-defined.

"Environmental limits"

The value of the macro FOPEN_MAX shall be at least eight, including the three standard text streams.

Forward references: the exit function ($4.10.4.3), the fgetc function ($4.9.7.1), the fopen function ($4.9.5.3), the fputc function ($4.9.7.3), the setbuf function ($4.9.5.5), the setvbuf function ($4.9.5.6).

4.9.4 Operations on files

4.9.4.1 The remove function

Synopsis

#include <stdio.h>

int remove(const char *filename);

Description

The remove function causes the file whose name is the string pointed to by filename to be no longer accessible by that name. A subsequent attempt to open that file using that name will fail, unless it is created anew. If the file is open, the behavior of the remove function is implementation-defined.

Returns

The remove function returns zero if the operation succeeds, nonzero if it fails.

4.9.4.2 The rename function

Synopsis

#include <stdio.h>

int rename(const char *old, const char *new);

Description

The rename function causes the file whose name is the string pointed to by old to be henceforth known by the name given by the string pointed to by new . The file named old is effectively removed. If a file named by the string pointed to by new exists prior to the call to the rename function, the behavior is implementation-defined.

Returns

The rename function returns zero if the operation succeeds, nonzero if it fails,/101/ in which case if the file existed previously it is still known by its original name.

4.9.4.3 The tmpfile function

Synopsis

#include <stdio.h>

FILE *tmpfile(void);

Description

The tmpfile function creates a temporary binary file that will automatically be removed when it is closed or at program termination. If the program terminates abnormally, whether an open temporary file is removed is implementation-defined. The file is opened for update with wb+ mode.

Returns

The tmpfile function returns a pointer to the stream of the file that it created. If the file cannot be created, the tmpfile function returns a null pointer.

Forward references: the fopen function ($4.9.5.3).

4.9.4.4 The tmpnam function

Synopsis

#include <stdio.h>

char *tmpnam(char *s);

Description

Synopsis

#include <stdio.h>

FILE *fopen(const char *filename, const char *mode);

Description

The fopen function opens the file whose name is the string pointed to by filename , and associates a stream with it.

The argument mode points to a string beginning with one of the following sequences:/103/

"r" open text file for reading

"w" truncate to zero length or create text file for writing

"a" append; open or create text file for writing at end-of-file

"rb" open binary file for reading

"wb" truncate to zero length or create binary file for writing

"ab" append; open or create binary file for writing at end-of-file

"r+" open text file for update (reading and writing)

"w+" truncate to zero length or create text file for update

"a+" append; open or create text file for update, writing at end-of-file

"r+b" or "rb+" open binary file for update (reading and writing)

"w+b" or "wb+" truncate to zero length or create binary file for update

"a+b" or "ab+" append; open or create binary file for update, writing at end-of-file

Opening a file with read mode ('r' as the first character in the mode argument) fails if the file does not exist or cannot be read.

Opening a file with append mode ('a' as the first character in the mode argument) causes all subsequent writes to the file to be forced to the then current end-of-file, regardless of intervening calls to the fseek function. In some implementations, opening a binary file with append mode ('b' as the second or third character in the mode argument) may initially position the file position indicator for the stream beyond the last data written, because of null character padding.

When a file is opened with update mode ('+' as the second or third character in the mode argument), both input and output may be performed on the associated stream. However, output may not be directly followed by input without an intervening call to the fflush function or to a file positioning function ( fseek , fsetpos , or rewind ), and input may not be directly followed by output without an intervening call to a file positioning function, unless the input operation encounters end-of-file. Opening a file with update mode may open or create a binary stream in some implementations.

When opened, a stream is fully buffered if and only if it can be determined not to refer to an interactive device. The error and end-of-file indicators for the stream are cleared.

Returns

The fopen function returns a pointer to the object controlling the stream. If the open operation fails, fopen returns a null pointer.

Forward references: file positioning functions ($4.9.9).

4.9.5.4 The freopen function

Synopsis

#include <stdio.h>

FILE *freopen(const char *filename, const char *mode,

FILE *stream);

Description

The freopen function opens the file whose name is the string pointed to by filename and associates the stream pointed to by stream with it. The mode argument is used just as in the fopen function./104/

The freopen function first attempts to close any file that is associated with the specified stream. Failure to close the file successfully is ignored. The error and end-of-file indicators for the stream are cleared.

Returns

The freopen function returns a null pointer if the open operation fails. Otherwise, freopen returns the value of stream .

4.9.5.5 The setbuf function

Synopsis

#include <stdio.h>

void setbuf(FILE *stream, char *buf);

Description

Except that it returns no value, the setbuf function is equivalent to the setvbuf function invoked with the values _IOFBF for mode and BUFSIZ for size , or (if buf is a null pointer), with the value _IONBF for mode .

Returns

The setbuf function returns no value.

Forward references: the setvbuf function ($4.9.5.6).

4.9.5.6 The setvbuf function

Synopsis

#include <stdio.h>

int setvbuf(FILE *stream, char *buf, int mode, size_t size);

Description

The setvbuf function may be used after the stream pointed to by stream has been associated with an open file but before any other operation is performed on the stream. The argument mode determines how stream will be buffered, as follows: _IOFBF causes input/output to be fully buffered; _IOLBF causes output to be line buffered; _IONBF causes input/output to be unbuffered. If buf is not a null pointer, the array it points to may be used instead of a buffer allocated by the setvbuf function./105/ The argument size specifies the size of the array. The contents of the array at any time are indeterminate.

Returns

The setvbuf function returns zero on success, or nonzero if an invalid value is given for mode or if the request cannot be honored.

4.9.6 Formatted input/output functions

4.9.6.1 The fprintf function

Synopsis

#include <stdio.h>

int fprintf(FILE *stream, const char *format, ...);

Description

The fprintf function writes output to the stream pointed to by stream , under control of the string pointed to by format that specifies how subsequent arguments are converted for output. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated (as always) but are otherwise ignored. The fprintf function returns when the end of the format string is encountered.

The format shall be a multibyte character sequence, beginning and ending in its initial shift state. The format is composed of zero or more directives: ordinary multibyte characters (not % ), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the character % . After the % , the following appear in sequence:

* Zero or more flags that modify the meaning of the conversion specification.

* An optional decimal integer specifying a minimum field width ./106/ If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left adjustment flag, described later, has been given) to the field width.

* An optional precision that gives the minimum number of digits to appear for the d , i , o , u , x , and X conversions, the number of digits to appear after the decimal-point character for e , E , and f conversions, the maximum number of significant digits for the g and G conversions, or the maximum number of characters to be written from a string in s conversion. The precision takes the form of a period ( . ) followed by an optional decimal integer; if the integer is omitted, it is treated as zero.

* An optional h specifying that a following d , i , o , u , x , or X conversion specifier applies to a short int or unsigned short int argument (the argument will have been promoted according to the integral promotions, and its value shall be converted to short int or unsigned short int before printing); an optional h specifying that a following n conversion specifier applies to a pointer to a short int argument; an optional l (ell) specifying that a following d , i , o , u , x , or X conversion specifier applies to a long int or unsigned long int argument; an optional l specifying that a following n conversion specifier applies to a pointer to a long int argument; or an optional L specifying that a following e , E , f , g , or G conversion specifier applies to a long double argument. If an h , l , or L appears with any other conversion specifier, the behavior is undefined.

* A character that specifies the type of conversion to be applied.

A field width or precision, or both, may be indicated by an asterisk * instead of a digit string. In this case, an int argument supplies the field width or precision. The arguments specifying field width or precision, or both, shall appear (in that order) before the argument (if any) to be converted. A negative field width argument is taken as a - flag followed by a positive field width. A negative precision argument is taken as if it were missing.

The flag characters and their meanings are The result of the conversion will be left-justified within the field. The result of a signed conversion will always begin with a plus or minus sign. If the first character of a signed conversion is not a sign, or if a signed conversion results in no characters, a space will be prepended to the result. If the space and + flags both appear, the space flag will be ignored. The result is to be converted to an ``alternate form.'' For o conversion, it increases the precision to force the first digit of the result to be a zero. For x (or X ) conversion, a nonzero result will have 0x (or 0X ) prepended to it. For e , E , f , g , and G conversions, the result will always contain a decimal-point character, even if no digits follow it (normally, a decimal-point character appears in the result of these conversions only if a digit follows it). For g and G conversions, trailing zeros will not be removed from the result. For other conversions, the behavior is undefined. For d , i , o , u , x , X , e , E , f , g , and G conversions, leading zeros (following any indication of sign or base) are used to pad to the field width; no space padding is performed. If the 0 and - flags both appear, the 0 flag will be ignored. For d , i , o , u , x , and X conversions, if a precision is specified, the 0 flag will be ignored. For other conversions, the behavior is undefined.

The conversion specifiers and their meanings are

The int argument is converted to signed decimal ( d or i ), unsigned octal ( o ), unsigned decimal ( u ), or unsigned hexadecimal notation ( x or X ); the letters abcdef are used for x conversion and the letters ABCDEF for X conversion. The precision specifies the minimum number of digits to appear; if the value being converted can be represented in fewer digits, it will be expanded with leading zeros. The default precision is 1. The result of converting a zero value with an explicit precision of zero is no characters. The double argument is converted to decimal notation in the style [-]ddd.ddd , where the number of digits after the decimal-point character is equal to the precision specification. If the precision is missing, it is taken as 6; if the precision is explicitly zero, no decimal-point character appears. If a decimal-point character appears, at least one digit appears before it. The value is rounded to the appropriate number of digits. The double argument is converted in the style [-]d.ddde+- dd , where there is one digit before the decimal-point character (which is nonzero if the argument is nonzero) and the number of digits after it is equal to the precision; if the precision is missing, it is taken as 6; if the precision is zero, no decimal-point character appears. The value is rounded to the appropriate number of digits. The E conversion specifier will produce a number with E instead of e introducing the exponent. The exponent always contains at least two digits. If the value is zero, the exponent is zero. The double argument is converted in style f or e (or in style E in the case of a G conversion specifier), with the precision specifying the number of significant digits. If an explicit precision is zero, it is taken as 1. The style used depends on the value converted; style e will be used only if the exponent resulting from such a conversion is less than -4 or greater than or equal to the precision. Trailing zeros are removed from the fractional portion of the result; a decimal-point character appears only if it is followed by a digit. The int argument is converted to an unsigned char , and the resulting character is written. The argument shall be a pointer to an array of character type./107/ Characters from the array are written up to (but not including) a terminating null character; if the precision is specified, no more than that many characters are written. If the precision is not specified or is greater than the size of the array, the array shall contain a null character. The argument shall be a pointer to void . The value of the pointer is converted to a sequence of printable characters, in an implementation-defined manner. The argument shall be a pointer to an integer into which is written the number of characters written to the output stream so far by this call to fprintf . No argument is converted. A % is written. No argument is converted. The complete conversion specification shall be %% .

If a conversion specification is invalid, the behavior is undefined./108/

If any argument is, or points to, a union or an aggregate (except for an array of character type using %s conversion, or a pointer cast to be a pointer to void using %p conversion), the behavior is undefined.

In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result.

Returns

The fprintf function returns the number of characters transmitted, or a negative value if an output error occurred.

"Environmental limit"

The minimum value for the maximum number of characters produced by any single conversion shall be 509.

Examples

To print a date and time in the form ``Sunday, July 3, 10:02,'' where weekday and month are pointers to strings:

#include <stdio.h>

fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",

weekday, month, day, hour, min);

To print PI to five decimal places:

#include <math.h>

#include <stdio.h>

fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));

4.9.6.2 The fscanf function

Synopsis

#include <stdio.h>

int fscanf(FILE *stream, const char *format, ...);

Description

The fscanf function reads input from the stream pointed to by stream , under control of the string pointed to by format that specifies the admissible input sequences and how they are to be converted for assignment, using subsequent arguments as pointers to the objects to receive the converted input. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated (as always) but are otherwise ignored.

The format shall be a multibyte character sequence, beginning and ending in its initial shift state. The format is composed of zero or more directives: one or more white-space characters; an ordinary multibyte character (not % ); or a conversion specification. Each conversion specification is introduced by the character % . After the % , the following appear in sequence:

* An optional assignment-suppressing character * .

* An optional decimal integer that specifies the maximum field width.

* An optional h , l (ell) or L indicating the size of the receiving object. The conversion specifiers d , i , and n shall be preceded by h if the corresponding argument is a pointer to short int rather than a pointer to int , or by l if it is a pointer to long int . Similarly, the conversion specifiers o , u , and x shall be preceded by h if the corresponding argument is a pointer to unsigned short int rather than a pointer to unsigned int , or by l if it is a pointer to unsigned long int . Finally, the conversion specifiers e , f , and g shall be preceded by l if the corresponding argument is a pointer to double rather than a pointer to float , or by L if it is a pointer to long double . If an h , l , or L appears with any other conversion specifier, the behavior is undefined.

* A character that specifies the type of conversion to be applied. The valid conversion specifiers are described below.

The fscanf function executes each directive of the format in turn. If a directive fails, as detailed below, the fscanf function returns. Failures are described as input failures (due to the unavailability of input characters), or matching failures (due to inappropriate input).

A directive composed of white space is executed by reading input up to the first non-white-space character (which remains unread), or until no more characters can be read.

A directive that is an ordinary multibyte character is executed by reading the next characters of the stream. If one of the characters differs from one comprising the directive, the directive fails, and the differing and subsequent characters remain unread.

A directive that is a conversion specification defines a set of matching input sequences, as described below for each specifier. A conversion specification is executed in the following steps:

Input white-space characters (as specified by the isspace function) are skipped, unless the specification includes a [ , c , or n specifier.

An input item is read from the stream, unless the specification includes an n specifier. An input item is defined as the longest sequence of input characters (up to any specified maximum field width) which is an initial subsequence of a matching sequence. The first character, if any, after the input item remains unread. If the length of the input item is zero, the execution of the directive fails: this condition is a matching failure, unless an error prevented input from the stream, in which case it is an input failure.

Except in the case of a % specifier, the input item (or, in the case of a %n directive, the count of input characters) is converted to a type appropriate to the conversion specifier. If the input item is not a matching sequence, the execution of the directive fails: this condition is a matching failure. Unless assignment suppression was indicated by a * , the result of the conversion is placed in the object pointed to by the first argument following the format argument that has not already received a conversion result. If this object does not have an appropriate type, or if the result of the conversion cannot be represented in the space provided, the behavior is undefined.

The following conversion specifiers are valid:

Matches an optionally signed decimal integer, whose format is the same as expected for the subject sequence of the strtol function with the value 10 for the base argument. The corresponding argument shall be a pointer to integer. Matches an optionally signed integer, whose format is the same as expected for the subject sequence of the strtol function with the value 0 for the base argument. The corresponding argument shall be a pointer to integer. Matches an optionally signed octal integer, whose format is the same as expected for the subject sequence of the strtoul function with the value 8 for the base argument. The corresponding argument shall be a pointer to unsigned integer. Matches an optionally signed decimal integer, whose format is the same as expected for the subject sequence of the strtoul function with the value 10 for the base argument. The corresponding argument shall be a pointer to unsigned integer. Matches an optionally signed hexadecimal integer, whose format is the same as expected for the subject sequence of the strtoul function with the value 16 for the base argument. The corresponding argument shall be a pointer to unsigned integer. Matches an optionally signed floating-point number, whose format is the same as expected for the subject string of the strtod function. The corresponding argument shall be a pointer to floating. Matches a sequence of non-white-space characters.rN The corresponding argument shall be a pointer to the initial character of an array large enough to accept the sequence and a terminating null character, which will be added automatically. Matches a nonempty sequence of charactersrN from a set of expected characters (the scanset ). The corresponding argument shall be a pointer to the initial character of an array large enough to accept the sequence and a terminating null character, which will be added automatically. The conversion specifier includes all subsequent characters in the format string, up to and including the matching right bracket ( ] ). The characters between the brackets (the scanlist ) comprise the scanset, unless the character after the left bracket is a circumflex ( ^ ), in which case the scanset contains all characters that do not appear in the scanlist between the circumflex and the right bracket. As a special case, if the conversion specifier begins with [] or [^] , the right bracket character is in the scanlist and the next right bracket character is the matching right bracket that ends the specification. If a - character is in the scanlist and is not the first, nor the second where the first character is a ^ , nor the last character, the behavior is implementation-defined. Matches a sequence of charactersrN of the number specified by the field width (1 if no field width is present in the directive). The corresponding argument shall be a pointer to the initial character of an array large enough to accept the sequence. No null character is added. Matches an implementation-defined set of sequences, which should be the same as the set of sequences that may be produced by the %p conversion of the fprintf function. The corresponding argument shall be a pointer to a pointer to void. The interpretation of the input item is implementation-defined; however, for any input item other than a value converted earlier during the same program execution, the behavior of the %p conversion is undefined. No input is consumed. The corresponding argument shall be a pointer to integer into which is to be written the number of characters read from the input stream so far by this call to the fscanf function. Execution of a %n directive does not increment the assignment count returned at the completion of execution of the fscanf function. Matches a single % ; no conversion or assignment occurs. The complete conversion specification shall be %% .

If a conversion specification is invalid, the behavior is undefined./110/

The conversion specifiers E , G , and X are also valid and behave the same as, respectively, e , g , and x .

If end-of-file is encountered during input, conversion is terminated. If end-of-file occurs before any characters matching the current directive have been read (other than leading white space, where permitted), execution of the current directive terminates with an input failure; otherwise, unless execution of the current directive is terminated with a matching failure, execution of the following directive (if any) is terminated with an input failure.

If conversion terminates on a conflicting input character, the offending input character is left unread in the input stream. Trailing white space (including new-line characters) is left unread unless matched by a directive. The success of literal matches and suppressed assignments is not directly determinable other than via the %n directive.

Returns

The fscanf function returns the value of the macro EOF if an input failure occurs before any conversion. Otherwise, the fscanf function returns the number of input items assigned, which can be fewer than provided for, or even zero, in the event of an early matching failure.

Examples

The call:

#include <stdio.h>

int n, i; float x; char name[50];

n = fscanf(stdin, "%d%f%s", &i, &x, name);

with the input line:

25 54.32E-1 thompson

will assign to n the value 3, to i the value 25, to x the value 5.432, and name will contain thompson\0 . Or:

#include <stdio.h>

int i; float x; char name[50];

fscanf(stdin, "%2d%f%*d %[0123456789]", &i, &x, name);

with input:

56789 0123 56a72

will assign to i the value 56 and to x the value 789.0, will skip 0123, and name will contain 56\0 . The next character read from the input stream will be a .

To accept repeatedly from stdin a quantity, a unit of measure and an item name:

#include <stdio.h>

int count; float quant; char units[21], item[21];

while (!feof(stdin) && !ferror(stdin)) {

count = fscanf(stdin, "%f%20s of %20s",

&quant, units, item);

fscanf(stdin,"%*[^\n]");

}

If the stdin stream contains the following lines:

2 quarts of oil

-12.8degrees Celsius

lots of luck

10.0LBS of fertilizer

100ergs of energy

the execution of the above example will be equivalent to the following assignments:

quant = 2; strcpy(units, "quarts"); strcpy(item, "oil");

count = 3;

quant = -12.8; strcpy(units, "degrees");

count = 2; /* "C" fails to match "o" */

count = 0; /* "l" fails to match "%f" */

quant = 10.0; strcpy(units, "LBS"); strcpy(item, "fertilizer");

count = 3;

count = 0; /* "100e" fails to match "%f" */

count = EOF;

Forward references: the strtod function ($4.10.1.4), the strtol function ($4.10.1.5), the strtoul function ($4.10.1.6).

4.9.6.3 The printf function

Synopsis

#include <stdio.h>

int printf(const char *format, ...);

Description

The printf function is equivalent to fprintf with the argument stdout interposed before the arguments to printf .

Returns

The printf function returns the number of characters transmitted, or a negative value if an output error occurred.

4.9.6.4 The scanf function

Synopsis

#include <stdio.h>

int scanf(const char *format, ...);

Description

The scanf function is equivalent to fscanf with the argument stdin interposed before the arguments to scanf .

Returns

The scanf function returns the value of the macro EOF if an input failure occurs before any conversion. Otherwise, the scanf function returns the number of input items assigned, which can be fewer than provided for, or even zero, in the event of an early matching failure.

4.9.6.5 The sprintf function

Synopsis

#include <stdio.h>

int sprintf(char *s, const char *format, ...);

escription

The sprintf function is equivalent to fprintf , except that the argument s specifies an array into which the generated output is to be written, rather than to a stream. A null character is written at the end of the characters written; it is not counted as part of the returned sum. If copying takes place between objects that overlap, the behavior is undefined.

Returns

The sprintf function returns the number of characters written in the array, not counting the terminating null character.

4.9.6.6 The sscanf function

Synopsis

#include <stdio.h>

int sscanf(const char *s, const char *format, ...);

Description

The sscanf function is equivalent to fscanf , except that the argument s specifies a string from which the input is to be obtained, rather than from a stream. Reaching the end of the string is equivalent to encountering end-of-file for the fscanf function. If copying takes place between objects that overlap, the behavior is undefined.

Returns

The sscanf function returns the value of the macro EOF if an input failure occurs before any conversion. Otherwise, the sscanf function returns the number of input items assigned, which can be fewer than provided for, or even zero, in the event of an early matching failure.

4.9.6.7 The vfprintf function

Synopsis

#include <stdarg.h>

#include <stdio.h>

int vfprintf(FILE *stream, const char *format, va_list arg);

Description

The vfprintf function is equivalent to fprintf , with the variable argument list replaced by arg , which has been initialized by the va_start macro (and possibly subsequent va_arg calls). The vfprintf function does not invoke the va_end macro.rN

Returns

The vfprintf function returns the number of characters transmitted, or a negative value if an output error occurred.

Example

The following shows the use of the vfprintf function in a general error-reporting routine.

#include <stdarg.h>

#include <stdio.h>

void error(char *function_name, char *format, ...)

{

va_list args;

va_start(args, format);

/* print out name of function causing error */

fprintf(stderr, "ERROR in %s: ", function_name);

/* print out remainder of message */

vfprintf(stderr, format, args);

va_end(args);

}

4.9.6.8 The vprintf function

Synopsis

#include <stdarg.h>

#include <stdio.h>

int vprintf(const char *format, va_list arg);

Description

The vprintf function is equivalent to printf , with the variable argument list replaced by arg , which has been initialized by the va_start macro (and possibly subsequent va_arg calls). The vprintf function does not invoke the va_end macro.rN

Returns

The vprintf function returns the number of characters transmitted, or a negative value if an output error occurred.

4.9.6.9 The vsprintf function

Synopsis

#include <stdarg.h>

Synopsis

#include <stdio.h>

int ungetc(int c, FILE *stream);

Description

4.9.9.1 The fgetpos function

Synopsis

#include <stdio.h>

int fgetpos(FILE *stream, fpos_t *pos);

Description

The fgetpos function stores the current value of the file position indicator for the stream pointed to by stream in the object pointed to by pos. The value stored contains unspecified information usable by the fsetpos function for repositioning the stream to its position at the time of the call to the fgetpos function.

Returns

If successful, the fgetpos function returns zero; on failure, the fgetpos function returns nonzero and stores an implementation-defined positive value in errno .

Forward references: the fsetpos function ($4.9.9.3).

4.9.9.2 The fseek function

Synopsis

#include <stdio.h>

int fseek(FILE *stream, long int offset, int whence);

Description

The fseek function sets the file position indicator for the stream pointed to by stream .

For a binary stream, the new position, measured in characters from the beginning of the file, is obtained by adding offset to the position specified by whence . The specified point is the beginning of the file for SEEK_SET , the current value of the file position indicator for SEEK_CUR , or end-of-file for SEEK_END . A binary stream need not meaningfully support fseek calls with a whence value of SEEK_END .

For a text stream, either offset shall be zero, or offset shall be a value returned by an earlier call to the ftell function on the same stream and whence shall be SEEK_SET .

A successful call to the fseek function clears the end-of-file indicator for the stream and undoes any effects of the ungetc function on the same stream. After an fseek call, the next operation on an update stream may be either input or output.

Returns

The fseek function returns nonzero only for a request that cannot be satisfied.

Forward references: the ftell function ($4.9.9.4).

4.9.9.3 The fsetpos function

Synopsis

#include <stdio.h>

int fsetpos(FILE *stream, const fpos_t *pos);

Description

The fsetpos function sets the file position indicator for the stream pointed to by stream according to the value of the object pointed to by pos , which shall be a value returned by an earlier call to the fgetpos function on the same stream.

A successful call to the fsetpos function clears the end-of-file indicator for the stream and undoes any effects of the ungetc function on the same stream. After an fsetpos call, the next operation on an update stream may be either input or output.

Returns

If successful, the fsetpos function returns zero; on failure, the fsetpos function returns nonzero and stores an implementation-defined positive value in errno .

4.9.9.4 The ftell function

Synopsis

#include <stdio.h>

long int ftell(FILE *stream);

Description

The ftell function obtains the current value of the file position indicator for the stream pointed to by stream . For a binary stream, the value is the number of characters from the beginning of the file. For a text stream, its file position indicator contains unspecified information, usable by the fseek function for returning the file position indicator for the stream to its position at the time of the ftell call; the difference between two such return values is not necessarily a meaningful measure of the number of characters written or read.

Returns

If successful, the ftell function returns the current value of the file position indicator for the stream. On failure, the ftell function returns -1L and stores an implementation-defined positive value in errno .

4.9.9.5 The rewind function

Synopsis

#include <stdio.h>

void rewind(FILE *stream);

Description

The rewind function sets the file position indicator for the stream pointed to by stream to the beginning of the file. It is equivalent to

(void)fseek(stream, 0L, SEEK_SET)

except that the error indicator for the stream is also cleared.

Returns

The rewind function returns no value.

4.9.10 Error-handling functions

4.9.10.1 The clearerr function

Synopsis

#include <stdio.h>

void clearerr(FILE *stream);

Description

The clearerr function clears the end-of-file and error indicators for the stream pointed to by stream .

Returns

The clearerr function returns no value.

4.9.10.2 The feof function

Synopsis

#include <stdio.h>

int feof(FILE *stream);

Description

The feof function tests the end-of-file indicator for the stream pointed to by stream .

Returns

The feof function returns nonzero if and only if the end-of-file indicator is set for stream .

4.9.10.3 The ferror function

Synopsis

#include <stdio.h>

int ferror(FILE *stream);

Description

The ferror function tests the error indicator for the stream pointed to by stream .

Returns

The ferror function returns nonzero if and only if the error indicator is set for stream .

4.9.10.4 The perror function

Synopsis

#include <stdio.h>

void perror(const char *s);

Description

The perror function maps the error number in the integer expression errno to an error message. It writes a sequence of characters to the standard error stream thus: first (if s is not a null pointer and the character pointed to by s is not the null character), the string pointed to by s followed by a colon and a space; then an appropriate error message string followed by a new-line character. The contents of the error message strings are the same as those returned by the strerror function with argument errno , which are implementation-defined.

Returns

The perror function returns no value.

Forward references: the strerror function ($4.11.6.2).

4.10 GENERAL UTILITIES <stdlib.h>

The header <stdlib.h> declares four types and several functions of general utility, and defines several macros./113/

The types declared are size_t and wchar_t (both described in $4.1.5),

div_t

which is a structure type that is the type of the value returned by the div function, and

ldiv_t

which is a structure type that is the type of the value returned by the ldiv function.

The macros defined are NULL (described in $4.1.5);

EXIT_FAILURE

and

EXIT_SUCCESS

which expand to integral expressions that may be used as the argument to the exit function to return unsuccessful or successful termination status, respectively, to the host environment;

RAND_MAX

which expands to an integral constant expression, the value of which is the maximum value returned by the rand function; and

MB_CUR_MAX

which expands to a positive integer expression whose value is the maximum number of bytes in a multibyte character for the extended character set specified by the current locale (category LC_CTYPE ), and whose value is never greater than MB_LEN_MAX .

4.10.1 String conversion functions

The functions atof , atoi , and atol need not affect the value of the integer expression errno on an error. If the value of the result cannot be represented, the behavior is undefined.

4.10.1.1 The atof function

Synopsis

#include <stdlib.h>

double atof(const char *nptr);

Description

The atof function converts the initial portion of the string pointed to by nptr to double representation. Except for the behavior on error, it is equivalent to

strtod(nptr, (char **)NULL)

Returns

The atof function returns the converted value.

Forward references: the strtod function ($4.10.1.4).

4.10.1.2 The atoi function

Synopsis

#include <stdlib.h>

int atoi(const char *nptr);

Description

The atoi function converts the initial portion of the string pointed to by nptr to int representation. Except for the behavior on error, it is equivalent to

(int)strtol(nptr, (char **)NULL, 10)

Returns

The atoi function returns the converted value.

Synopsis

#include <stdlib.h>

unsigned long int strtoul(const char *nptr, char **endptr,

int base);

Description

The strtoul function converts the initial portion of the string pointed to by nptr to unsigned long int representation. First it decomposes the input string into three parts: an initial, possibly empty, sequence of white-space characters (as specified by the isspace function), a subject sequence resembling an unsigned integer represented in some radix determined by the value of base , and a final string of one or more unrecognized characters, including the terminating null character of the input string. Then it attempts to convert the subject sequence to an unsigned integer, and returns the result.

In other than the C locale, additional implementation-defined subject sequence forms may be accepted.

Returns

The strtoul function returns the converted value, if any. If no conversion could be performed, zero is returned. If the correct value would cause overflow, ULONG_MAX is returned, and the value of the macro ERANGE is stored in errno .

4.10.2 Pseudo-random sequence generation functions

4.10.2.1 The rand function

Synopsis

#include <stdlib.h>

int rand(void);

Description

The rand function computes a sequence of pseudo-random integers in the range 0 to RAND_MAX .

The implementation shall behave as if no library function calls the rand function.

Returns

The rand function returns a pseudo-random integer.

"Environmental limit"

The value of the RAND_MAX macro shall be at least 32767.

4.10.2.2 The srand function

Synopsis

#include <stdlib.h>

void srand(unsigned int seed);

Description

The srand function uses the argument as a seed for a new sequence of pseudo-random numbers to be returned by subsequent calls to rand . If srand is then called with the same seed value, the sequence of pseudo-random numbers shall be repeated. If rand is called before any calls to srand have been made, the same sequence shall be generated as when srand is first called with a seed value of 1.

The implementation shall behave as if no library function calls the srand function.

Returns

The srand function returns no value.

Example

The following functions define a portable implementation of rand and srand . Specifying the semantics makes it possible to determine reproducibly the behavior of programs that use pseudo-random sequences. This facilitates the testing of portable applications in different implementations.

static unsigned long int next = 1;

int rand(void) /* RAND_MAX assumed to be 32767 */

{

next = next * 1103515245 + 12345;

return (unsigned int)(next/65536) % 32768;

char *getenv(const char *name);

Description

The getenv function searches an environment list ,provided by the host environment, for a string that matches the string pointed to by name . The set of environment names and the method for altering the environment list are implementation-defined.

The implementation shall behave as if no library function calls the getenv function.

Returns

The getenv function returns a pointer to a string associated with the matched list member. The array pointed to shall not be modified by the program, but may be overwritten by a subsequent call to the getenv function. If the specified name cannot be found, a null pointer is returned.

4.10.4.5 The system function

Synopsis

#include <stdlib.h>

int system(const char *string);

escription

The system function passes the string pointed to by string to the host environment to be executed by a command processor in an implementation-defined manner. A null pointer may be used for string to inquire whether a command processor exists.

Returns

If the argument is a null pointer, the system function returns nonzero only if a command processor is available. If the argument is not a null pointer, the system function returns an implementation-defined value.

4.10.5 Searching and sorting utilities

4.10.5.1 The bsearch function

Synopsis

#include <stdlib.h>

void *bsearch(const void *key, const void *base,

size_t nmemb, size_t size,

int (*compar)(const void *, const void *));

Description

The bsearch function searches an array of nmemb objects, the initial member of which is pointed to by base , for a member that matches the object pointed to by key . The size of each member of the array is specified by size .

The contents of the array shall be in ascending sorted order according to a comparison function pointed to by compar ,/116/ induces which is called with two arguments that point to the key object and to an array member, in that order. The function shall return an integer less than, equal to, or greater than zero if the key object is considered, respectively, to be less than, to match, or to be greater than the array member.

Returns

The bsearch function returns a pointer to a matching member of the array, or a null pointer if no match is found. If two members compare as equal, which member is matched is unspecified.

4.10.5.2 The qsort function

Synopsis

#include <stdlib.h>

void qsort(void *base, size_t nmemb, size_t size,

Synopsis

#include <stdlib.h>

long int labs(long int j);

escription

The labs function is similar to the abs function, except that the argument and the returned value each have type long int .

4.10.6.4 The ldiv function

Synopsis

#include <stdlib.h>

ldiv_t ldiv(long int numer, long int denom);

escription

The ldiv function is similar to the div function, except that the arguments and the members of the returned structure (which has type ldiv_t ) all have type long int .

4.10.7 Multibyte character functions

The behavior of the multibyte character functions is affected by the LC_CTYPE category of the current locale. For a state-dependent encoding, each function is placed into its initial state by a call for which its character pointer argument, s , is a null pointer. Subsequent calls with s as other than a null pointer cause the internal state of the function to be altered as necessary. A call with s as a null pointer causes these functions to return a nonzero value if encodings have state dependency, and zero otherwise. After the LC_CTYPE category is changed, the shift state of these functions is indeterminate.

4.10.7.1 The mblen function

Synopsis

#include <stdlib.h>

int mblen(const char *s, size_t n);

Description

If s is not a null pointer, the mblen function determines the number of bytes comprising the multibyte character pointed to by s . Except that the shift state of the mbtowc function is not affected, it is equivalent to

mbtowc((wchar_t *)0, s, n);

The implementation shall behave as if no library function calls the mblen function.

Returns

If s is a null pointer, the mblen function returns a nonzero or zero value, if multibyte character encodings, respectively, do or do not have state-dependent encodings. If s is not a null pointer, the mblen function either returns 0 (if s points to the null character), or returns the number of bytes that comprise the multibyte character (if the next n or fewer bytes form a valid multibyte character), or returns -1 (if they do not form a valid multibyte character).

Forward references: the mbtowc function ($4.10.7.2).

4.10.7.2 The mbtowc function

Synopsis

#include <stdlib.h>

int mbtowc(wchar_t *pwc, const char *s, size_t n);

Description

If s is not a null pointer, the mbtowc function determines the number of bytes that comprise the multibyte character pointed to by s . It then determines the code for value of type wchar_t that corresponds to that multibyte character. (The value of the code corresponding to the null character is zero.) If the multibyte character is valid and pwc is not a null pointer, the mbtowc function stores the code in the object pointed to by pwc. At most n bytes of the array pointed to by s will be examined.

The implementation shall behave as if no library function calls the mbtowc function.

Returns

If s is a null pointer, the mbtowc function returns a nonzero or zero value, if multibyte character encodings, respectively, do or do not have state-dependent encodings. If s is not a null pointer, the mbtowc function either returns 0 (if s points to the null character), or returns the number of bytes that comprise the converted multibyte character (if the next n or fewer bytes form a valid multibyte character), or returns -1 (if they do not form a valid multibyte character).

In no case will the value returned be greater than n or the value of the MB_CUR_MAX macro.

4.10.7.3 The wctomb function

Synopsis

#include <stdlib.h>

int wctomb(char *s, wchar_t wchar);

4.11.1 String function conventions

If the array pointed to by s2 is a string that is shorter than n characters, null characters are appended to the copy in the array pointed to by s1 , until n characters in all have been written.

Returns

The strncpy function returns the value of s1 .

4.11.3 Concatenation functions

4.11.3.1 The strcat function

Synopsis

#include <string.h>

char *strcat(char *s1, const char *s2);

Description

The strcat function appends a copy of the string pointed to by s2 (including the terminating null character) to the end of the string pointed to by s1 . The initial character of s2 overwrites the null character at the end of s1 . If copying takes place between objects that overlap, the behavior is undefined.

Returns

The strcat function returns the value of s1 .

4.11.3.2 The strncat function

Synopsis

#include <string.h>

char *strncat(char *s1, const char *s2, size_t n);

Synopsis

#include <string.h>

size_t strxfrm(char *s1, const char *s2, size_t n);

Description

Synopsis

#include <string.h>

char *strtok(char *s1, const char *s2);

Description

A sequence of calls to the strtok function breaks the string pointed to by s1 into a sequence of tokens, each of which is delimited by a character from the string pointed to by s2 . The first call in the sequence has s1 as its first argument, and is followed by calls with a null pointer as their first argument. The separator string pointed to by s2 may be different from call to call.

The first call in the sequence searches the string pointed to by s1 for the first character that is not contained in the current separator string pointed to by s2 . If no such character is found, then there are no tokens in the string pointed to by s1 and the strtok function returns a null pointer. If such a character is found, it is the start of the first token.

The strtok function then searches from there for a character that is contained in the current separator string. If no such character is found, the current token extends to the end of the string pointed to by s1 , and subsequent searches for a token will return a null pointer. If such a character is found, it is overwritten by a null character, which terminates the current token. The strtok function saves a pointer to the following character, from which the next search for a token will start.

Each subsequent call, with a null pointer as the value of the first argument, starts searching from the saved pointer and behaves as described above.

The implementation shall behave as if no library function calls the strtok function.

Returns

The strtok function returns a pointer to the first character of a token, or a null pointer if there is no token.

Example

#include <string.h>

size_t strlen(const char *s);

Description

The strlen function computes the length of the string pointed to by s .

Returns

The strlen function returns the number of characters that precede the terminating null character.

4.12 DATE AND TIME <time.h>

4.12.1 Components of time

The header <time.h> defines two macros, and declares four types and several functions for manipulating time. Many functions deal with a calendar time that represents the current date (according to the Gregorian calendar) and time. Some functions deal with local time ,which is the calendar time expressed for some specific time zone, and with Daylight Saving Time ,which is a temporary change in the algorithm for determining local time. The local time zone and Daylight Saving Time are implementation-defined.

The macros defined are NULL (described in $4.1.5); and

CLK_TCK

which is the number per second of the value returned by the clock function.

The types declared are size_t (described in $4.1.5);

clock_t

and

time_t

which are arithmetic types capable of representing times; and

struct tm

which holds the components of a calendar time, called the broken-down time .The structure shall contain at least the following members, in any order. The semantics of the members and their normal ranges are expressed in the comments./123/

int tm_sec; /* seconds after the minute --- [0, 60] */

int tm_min; /* minutes after the hour --- [0, 59] */

int tm_hour; /* hours since midnight --- [0, 23] */

int tm_mday; /* day of the month --- [1, 31] */

int tm_mon; /* months since January --- [0, 11] */

int tm_year; /* years since 1900 */

int tm_wday; /* days since Sunday --- [0, 6] */

int tm_yday; /* days since January 1 --- [0, 365] */

int tm_isdst; /* Daylight Saving Time flag */

The value of tm_isdst is positive if Daylight Saving Time is in effect, zero if Daylight Saving Time is not in effect, and negative if the information is not available.

4.12.2 Time manipulation functions

4.12.2.1 The clock function

Synopsis

#include <time.h>

clock_t clock(void);

Description

The clock function determines the processor time used.

Returns

The clock function returns the implementation's best approximation to the processor time used by the program since the beginning of an implementation-defined era related only to the program invocation. To determine the time in seconds, the value returned by the clock function should be divided by the value of the macro CLK_TCK . If the processor time used is not available or its value cannot be represented, the function returns the value (clock_t)-1 .

4.12.2.2 The difftime function

Synopsis

#include <time.h>

double difftime(time_t time1, time_t time0);

Description

The difftime function computes the difference between two calendar times: time1 - time0 .

Returns

The difftime function returns the difference expressed in seconds as a double .

4.12.2.3 The mktime function

Synopsis

#include <time.h>

time_t mktime(struct tm *timeptr);

Description

The mktime function converts the broken-down time, expressed as local time, in the structure pointed to by timeptr into a calendar time value with the same encoding as that of the values returned by the time function. The original values of the tm_wday and tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated above./124/ On successful completion, the values of the tm_wday and tm_yday components of the structure are set appropriately, and the other components are set to represent the specified calendar time, but with their values forced to the ranges indicated above; the final value of tm_mday is not set until tm_mon and tm_year are determined.

Returns

The mktime function returns the specified calendar time encoded as a value of type time_t . If the calendar time cannot be represented, the function returns the value (time_t)-1 .

Example

What day of the week is July 4, 2001?

#include <stdio.h>

#include <time.h>

static const char *const wday[] = {

"Sunday", "Monday", "Tuesday", "Wednesday",

"Thursday", "Friday", "Saturday", "-unknown-"

};

struct tm time_str;

time_str.tm_year = 2001 - 1900;

time_str.tm_mon = 7 - 1;

time_str.tm_mday = 4;

time_str.tm_hour = 0;

time_str.tm_min = 0;

time_str.tm_sec = 1;

time_str.tm_isdst = -1;

if (mktime(&time_str) =^= -1)

time_str.tm_wday = 7;

printf("%s\n", wday[time_str.tm_wday]);

4.12.2.4 The time function

Synopsis

#include <time.h>

time_t time(time_t *timer);

Description

The time function determines the current calendar time. The encoding of the value is unspecified.

Returns

The time function returns the implementation's best approximation to the current calendar time. The value (time_t)-1 is returned if the calendar time is not available. If timer is not a null pointer, the return value is also assigned to the object it points to.

4.12.3 Time conversion functions

Except for the strftime function, these functions return values in one of two static objects: a broken-down time structure and an array of char . Execution of any of the functions may overwrite the information returned in either of these objects by any of the other functions. The implementation shall behave as if no other library functions call these functions.

4.12.3.1 The asctime function

Synopsis

#include <time.h>

char *asctime(const struct tm *timeptr);

Description

The asctime function converts the broken-down time in the structure pointed to by timeptr into a string in the form

Sun Sep 16 01:03:52 1973\n\0

using the equivalent of the following algorithm.

char *asctime(const struct tm *timeptr)

{

static const char wday_name[7][3] = {

"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"

};

static const char mon_name[12][3] = {

"Jan", "Feb", "Mar", "Apr", "May", "Jun",

"Jul", "Aug", "Sep", "Oct", "Nov", "Dec"

};

static char result[26];

sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\n",

wday_name[timeptr->tm_wday],

mon_name[timeptr->tm_mon],

timeptr->tm_mday, timeptr->tm_hour,

timeptr->tm_min, timeptr->tm_sec,

1900 + timeptr->tm_year);

return result;

}

Returns

The asctime function returns a pointer to the string.

4.12.3.2 The ctime function

Synopsis

#include <time.h>

char *ctime(const time_t *timer);

Description

The ctime function converts the calendar time pointed to by timer to local time in the form of a string. It is equivalent to

asctime(localtime(timer))

Returns

The ctime function returns the pointer returned by the asctime function with that broken-down time as argument.

Forward references: the localtime function ($4.12.3.4).

4.12.3.3 The gmtime function

Synopsis

#include <time.h>

struct tm *gmtime(const time_t *timer);

Description

The gmtime function converts the calendar time pointed to by timer into a broken-down time, expressed as Coordinated Universal Time (UTC).

Returns

The gmtime function returns a pointer to that object, or a null pointer if UTC is not available.

4.12.3.4 The localtime function

Synopsis

#include <time.h>

struct tm *localtime(const time_t *timer);

Description

The localtime function converts the calendar time pointed to by timer into a broken-down time, expressed as local time.

Returns

The localtime function returns a pointer to that object.

4.12.3.5 The strftime function

Synopsis

#include <time.h>

size_t strftime(char *s, size_t maxsize,

const char *format, const struct tm *timeptr);

escription

The strftime function places characters into the array pointed to by s as controlled by the string pointed to by format . The format shall be a multibyte character sequence, beginning and ending in its initial shift state. The format string consists of zero or more conversion specifications and ordinary multibyte characters. A conversion specification consists of a % character followed by a character that determines the conversion specification's behavior. All ordinary multibyte characters (including the terminating null character) are copied unchanged into the array. If copying takes place between objects that overlap, the behavior is undefined. No more than maxsize characters are placed into the array. Each conversion specification is replaced by appropriate characters as described in the following list. The appropriate characters are determined by the program's locale and by the values contained in the structure pointed to by timeptr .

is replaced by the locale's abbreviated weekday name. is replaced by the locale's full weekday name. is replaced by the locale's abbreviated month name. is replaced by the locale's full month name. is replaced by the locale's appropriate date and time representation. is replaced by the day of the month as a decimal number ( 01 - 31 ). is replaced by the hour (24-hour clock) as a decimal number ( 00 - 23 ). is replaced by the hour (12-hour clock) as a decimal number ( 01 - 12 ). is replaced by the day of the year as a decimal number ( 001 - 366 ). is replaced by the month as a decimal number ( 01 - 12 ). is replaced by the minute as a decimal number ( 00 - 59 ). is replaced by the locale's equivalent of either AM or PM . is replaced by the second as a decimal number ( 00 - 60 ). is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number ( 00 - 53 ). is replaced by the weekday as a decimal number [ 0 (Sunday)- 6 ]. is replaced by the week number of the year (Monday as the first day of the week) as a decimal number ( 00 - 53 ). is replaced by the locale's appropriate date representation. is replaced by the locale's appropriate time representation. is replaced by the year without century as a decimal number ( 00 - 99 ). is replaced by the year with century as a decimal number. is replaced by the time zone name, or by no characters if no time zone is determinable. is replaced by % .

If a conversion specification is not one of the above, the behavior is undefined.

Returns

If the total number of resulting characters including the terminating null character is not more than maxsize , the strftime function returns the number of characters placed into the array pointed to by s not including the terminating null character. Otherwise, zero is returned and the contents of the array are indeterminate.

NDP77
http://www.ndp77.net
webmaster Massimo F. ARENA
webmaster@ndp77.net