7.4.11 <stdio.h>

Performs processing relating to input/output of stream input/output file.
The following constants (macros) are all implementation-defined.

Type

Definition Name

Description

Constant
(macro)

FILE

Indicates a structure type that stores various control information including a pointer to the buffer, an error indicator, and an end-of-file indicator, which are required for stream input/output processing.

_IOFBF

Indicates full buffering of input/output as the buffer area usage method.

_IOLBF

Indicates line buffering of input/output as the buffer area usage method.

_IONBF

Indicates non-buffering of input/output as the buffer area usage method.

BUFSIZ

Indicates the buffer size required for input/output processing.

EOF

Indicates end-of-file, that is, no more input from a file.

L_tmpnam*

Indicates the size of an array large enough to store a string of a temporary file name generated by the tmpnam function.

SEEK_CUR

Indicates a shift of the current file read/write position to an offset from the current position.

SEEK_END

Indicates a shift of the current file read/write position to an offset from the end-of-file position.

SEEK_SET

Indicates a shift of the current file read/write position to an offset from the beginning of the file.

SYS_OPEN*

Indicates the number of files for which simultaneous opening is guaranteed by the implementation.

TMP_MAX*

Indicates the maximum number of unique file names that shall be generated by the tmpnam function.

stderr

Indicates the file pointer to the standard error file.

stdin

Indicates the file pointer to the standard input file.

stdout

Indicates the file pointer to the standard output file.

Function

fclose

Closes a stream input/output file.

fflush

Outputs stream input/output file buffer contents to the file.

fopen

Opens a stream input/output file under the specified file name.

freopen

Closes a currently open stream input/output file and reopens a new file under the specified file name.

setbuf

Defines and sets a stream input/output buffer area on the user program side.

setvbuf

Defines and sets a stream input/output buffer area on the user program side.

fprintf

Outputs data to a stream input/output file according to a format.

vfprintf

Outputs a variable parameter list to the specified stream input/output file according to a format.

printf

Converts data according to a format and outputs it to the standard output file (stdout).

vprintf

Outputs a variable parameter list to the standard output file (stdout) according to a format.

sprintf

Converts data according to a format and outputs it to the specified area.

sscanf

Inputs data from the specified storage area and converts it according to a format.

snprintf <-lang=c99>

Converts data according to a format and writes it to the specified array.

vsnprintf <-lang=c99>

Equivalent to snprintf with the variable argument list replaced by va_list.

vfscanf <-lang=c99>

Equivalent to fscanf with the variable argument list replaced by va_list.

vscanf <-lang=c99>

Equivalent to scanf with the variable argument list replaced by va_list.

vsscanf <-lang=c99>

Equivalent to sscanf with the variable argument list replaced by va_list.

fscanf

Inputs data from a stream input/output file and converts it according to a format.

scanf

Inputs data from the standard input file (stdin) and converts it according to a format.

vsprintf

Outputs a variable parameter list to the specified area according to a format.

fgetc

Inputs one character from a stream input/output file.

fgets

Inputs a string from a stream input/output file.

fputc

Outputs one character to a stream input/output file.

fputs

Outputs a string to a stream input/output file.

getc

(macro) Inputs one character from a stream input/output file.

getchar

(macro) Inputs one character from the standard input file.

gets

Inputs a string from the standard input file.

putc

(macro) Outputs one character to a stream input/output file.

putchar

(macro) Outputs one character to the standard output file.

puts

Outputs a string to the standard output file.

ungetc

Returns one character to a stream input/output file.

Function

fread

Inputs data from a stream input/output file to the specified storage area.

fwrite

Outputs data from a storage area to a stream input/output file.

fseek

Shifts the current read/write position in a stream input/output file.

ftell

Obtains the current read/write position in a stream input/output file.

rewind

Shifts the current read/write position in a stream input/output file to the beginning of the file.

clearerr

Clears the error state of a stream input/output file.

feof

Tests for the end of a stream input/output file.

ferror

Tests for stream input/output file error state.

perror

Outputs an error message corresponding to the error number to the standard error file (stderr).

Type

fpos_t

Indicates a type that can specify any position in a file.

Constant (macro)

FOPEN_MAX

Indicates the maximum number of files that can be opened simultaneously.

FILENAME_MAX

Indicates the maximum length of a file name that can be held.

Note

* These macros are not defined in this implementation.

Implementation-Defined Specifications

Item

Compiler Specifications

Whether the last line of the input text requires a new-line character indicating the end

Not specified. Depends on the low-level interface routine specifications.

Whether the space characters written immediately before the new-line character are read

Number of null characters added to data written in the binary file

Initial value of file position indicator in the append mode

Whether file data is lost after output to a text file

File buffering specifications

Whether a file with file length 0 exists

File name configuration rule

Whether the same file is opened simultaneously

Output data representation of the %p format conversion in the fprintf function

Hexadecimal representation.

Input data representation of the %p format conversion in the fscanf function.
The meaning of conversion specifier in the fscanf function

Hexadecimal representation.

If is not the first or last character or does not follow ^, the range from the previous character to the following character is indicated.

Value of errno specified by the fgetpos or ftell function

The fgetpos function is not supported.
The errno value for the ftell function is not specified. It depends on the low-level interface routine specifications.

Output format of messages generated by the perror function

See (a) below for the output message format.

 

(a) The output format of perror function is

<string>:<error message for the error number specified in error>

 

(b) Table 7.8 shows the format when displaying the floating-point infinity and not-a-number in printf and fprintf functions.

Table 7.8

Display Format of Infinity and Not-a-Number

Value

Display Format

Positive infinity

++++++

Negative infinity

------

Not-a-number

******

An example of a program that performs a series of input/output processing operations for a stream input/output file is shown in the following.

[Format]

 1   #include <stdio.h>
 2
 3  void main( )
 4  {
 5      int c;
 6      FILE *ifp, *ofp;
 7
 8      if ((ifp=fopen("INPUT.DAT","r"))==NULL){
 9          fprintf(stderr,"cannot open input file\n");
 10         exit(1);
 11      }
 12      if ((ofp=fopen("OUTPUT.DAT","w"))==NULL){
 13          fprintf(stderr,"cannot open output file\n");
 14          exit(1);
 15      }
 16      while ((c=getc(ifp))!=EOF)
 17         putc(c, ofp);
 18      fclose(ifp);
 19      fclose(ofp);
 20  }

Explanation:

This program copies the contents of file INPUT.DAT to file OUTPUT.DAT.

Input file INPUT.DAT is opened by the fopen function in line 8, and output file OUTPUT.DAT is opened by the fopen function in line 12. If opening fails, NULL is returned as the return value of the fopen function, an error message is output, and the program is terminated.

If the fopen function ends normally, the pointer to the data (FILE type) that stores information on the opened files is returned; these are set in variables ifp and ofp.

After successful opening, input/output is performed using these FILE type data.

When file processing ends, the files are closed with the fclose function.

 

fclose

Closes a stream input/output file.

[Format]

#include <stdio.h>
long fclose (FILE *fp);

[Parameters]

fp File pointer

[Return values]

Normal: 0

Abnormal: Nonzero

[Remarks]

The fclose function closes the stream input/output file indicated by file pointer fp.

If the output file of the stream input/output file is open and data that is not output remains in the buffer, that data is output to the file before it is closed.

If the input/output buffer was automatically allocated by the system, it is released.

 

fflush

Outputs the stream input/output file buffer contents to the file.

[Format]

#include <stdio.h>
long fflush (FILE *fp);

[Parameters]

fp File pointer

[Return values]

Normal: 0

Abnormal: Nonzero

[Remarks]

When the output file of the stream input/output file is open, the fflush function outputs the contents of the buffer that is not output for the stream input/output file specified by file pointer fp to the file. When the input file is open, the ungetc function specification is invalidated.

 

fopen

Opens a stream input/output file under the specified file name.

[Format]

#include <stdio.h>
FILE *fopen (const char *fname, const char *mode);

[Parameters]

fname Pointer to string indicating file name

mode Pointer to string indicating file access mode

[Return values]

Normal: File pointer indicating file information on opened file

Abnormal: NULL

[Remarks]

The fopen function opens the stream input/output file whose file name is the string pointed to by fname. If a file that does not exist is opened in write mode or append mode, a new file is created wherever possible. When an existing file is opened in write mode, writing processing is performed from the beginning of the file, and previously written file contents are erased.

When a file is opened in append mode, write processing is performed from the end-of-file position. When a file is opened in update mode, both input and output processing can be performed on the file. However, input cannot directly follow output without intervening execution of the fflush, fseek, or rewind function. Similarly, output cannot directly follow input without intervening execution of the fflush, fseek, or rewind function.

A string indicating the opening method may be added after the string indicating the file access mode.

 

freopen

Closes a currently open stream input/output file and reopens a new file under the specified file name.

[Format]

#include <stdio.h>
FILE *freopen (const char *fname, const char *mode, FILE *fp);

[Parameters]

fname Pointer to string indicating new file name

mode Pointer to string indicating file access mode

fp File pointer to currently open stream input/output file

[Return values]

Normal: fp

Abnormal: NULL

[Remarks]

The freopen function first closes the stream input/output file indicated by file pointer fp (the following processing is carried out even if this close processing is unsuccessful). Next, the freopen function opens the file indicated by file name fname for stream input/output, reusing the FILE structure pointed to by fp.

The freopen function is useful when there is a limit on the number of files being opened at one time.

The freopen function normally returns the same value as fp, but returns NULL when an error occurs.

 

setbuf

Defines and sets a stream input/output buffer area by the user program.

[Format]

#include <stdio.h>
void setbuf (FILE *fp, char buf[BUFSIZ]);

[Parameters]

fp File pointer

buf Pointer to buffer area

[Remarks]

The setbuf function defines the storage area pointed to by buf so that it can be used as an input/output buffer area for the stream input/output file indicated by file pointer fp. As a result, input/output processing is performed using a buffer area of size BUFSIZ.

 

setvbuf

Defines and sets a stream input/output buffer area by the user program.

[Format]

#include <stdio.h>
long setvbuf (FILE *fp, char *buf, long type, size_t size);

[Parameters]

fp File pointer

buf Pointer to buffer area

type Buffer management method

size Size of buffer area

[Return values]

Normal: 0

Abnormal: Nonzero

[Remarks]

The setvbuf function defines the storage area pointed to by buf so that it can be used as an input/output buffer area for the stream input/output file indicated by file pointer fp.

There are three ways of using this buffer area, as follows:

(a) When _IOFBF is specified as type

Input/output is fully buffered.

(b) When _IOLBF is specified as type

Input/output is line buffered; that is, input/output data is fetched from the buffer area when a new-line character is written, when the buffer area is full, or when input is requested.

(c) When _IONBF is specified as type

Input/output is unbuffered.
The setvbuf function usually returns 0. However, when an illegal value is specified for type or size, or when the request on how to use the buffer could not be accepted, a value other than 0 is returned.

The buffer area must not be released before the open stream input/output file is closed. In addition, the setvbuf function must be used between opening of the stream input/output file and execution of input/output processing.

 

fprintf

Outputs data to a stream input/output file according to the format.

[Format]

#include <stdio.h>
long fprintf (FILE *fp, const char *control[, arg]...);

[Parameters]

fp File pointer

control Pointer to string indicating format

arg, List of data to be output according to format

[Return values]

Normal: Number of characters converted and output

Abnormal: Negative value

[Remarks]

The fprintf function converts and edits parameter arg according to the string that represents the format pointed to by control, and outputs the result to the stream input/output file indicated by file pointer fp.

The fprintf function returns the number of characters converted and output when the function is terminated successfully, or a negative value if an error occurs.

The format specifications are shown below.

Overview of Formats

The string that represents the format is made up of two kinds of string.

-

Ordinary characters

A character other than a conversion specification shown below is output unchanged.

-

Conversion specifications

A conversion specification is a string beginning with % that specifies the conversion method for the following parameter. The conversion specifications format conforms to the following rules:

 

When there is no parameter to be actually output according to this conversion specification, the behavior is not guaranteed. In addition, when the number of parameters to be actually output is greater than the conversion specification, the excess parameters are ignored.

Description of Conversion Specifications

 

(a) Flags

Flags specify modifications to the data to be output, such as addition of a sign. The types of flag that can be specified and their meanings are shown in Table 7.9.

Table 7.9

Flag Types and Their Meanings

Type

Meaning

If the number of converted data characters is less than the field width, the data will be output left-justified within the field.

+

A plus or minus sign will be prefixed to the result of a signed conversion.

space

If the first character of a signed conversion result is not a sign, a space will be prefixed to the result. If the space and + flags are both specified, the space flag will be ignored.

#

The converted data is to be modified according to the conversion types described in table 6.10.

1. For c, d, i, s, and u conversions

This flag is ignored.

2. For o conversion

The converted data is prefixed with 0.

3. For x or X conversion

The converted data is prefixed with 0x (or 0X)

4. For e, E, f, g, and G conversions

A decimal point is output even if the converted data has no fractional part. With g and G conversions, the 0 suffixed to the converted data are not removed.

 

(b) Field width

The number of characters in the converted data to be output is specified as a decimal number.

If the number of converted data characters is less than the field width, the data is prefixed with spaces up to the field width. (However, if '-' is specified as a flag, spaces are suffixed to the data.)

If the number of converted data characters exceeds the field width, the field width is extended to allow the converted result to be output.

If the field width specification begins with 0, the output data is prefixed with characters "0", not spaces.

 

(c) Precision

The precision of the converted data is specified according to the type of conversion, as described in table 6.10.

The precision is specified in the form of a period (.) followed by a decimal integer. If the decimal integer is omitted, 0 is assumed to be specified.

If the specified precision is incompatible with the field width specification, the field width specification is ignored.

The precision specification has the following meanings according to the conversion type.

-

For d, i, o, u, x, and X conversions

The minimum number of digits in the converted data is specified.

-

For e, E, and f conversions

The number of digits after the decimal point in the converted data is specified.

-

For g and G conversions

The maximum number of significant digits in the converted data is specified.

-

For s conversion

The maximum number of printed digits is specified.

 

(d) Parameter size specification

For d, i, o, u, x, X, e, E, f, g, and G conversions (see table 6.10), the size (short type, long type, long long type, or long double type) of the data to be converted is specified. In other conversions, this specification is ignored. Table 7.10 shows the types of size specification and their meanings.

Table 7.10

Parameter Size Specification Types and Meanings

Type

Meaning

h

For d, i, o, u, x, and X conversions, specifies that the data to be converted is of short type or unsigned short type.

l

For d, i, o, u, x, and X conversions, specifies that the data to be converted is of long type, unsigned long type, or double type.

L

For e, E, f, g, and G conversions, specifies that the data to be converted is of long double type.

ll

For d, i, o, u, x, and X conversions, specifies that the data to be converted is of long long type or unsigned long long type. For n conversion, specifies that the data to be converted is of pointer type to long long type.

 

(e) Conversion specifier

The format into which the data is to be converted is specified.

If the data to be converted is structure or array type, or is a pointer pointing to those types, the behavior is not guaranteed except when a character array is converted by s conversion or when a pointer is converted by p conversion. Table 7.11 shows the conversion specifier and conversion methods. If a letter which is not shown in this table is specified as the conversion specifier, the behavior is not guaranteed. The behavior, if a character that is not a letter is specified, depends on the compiler.

Table 7.11

Conversion Specifiers and Conversion Methods

Conversion Specifier

Conversion Type

Conversion Method

Data Type Subject to Conversion

Notes on Precision

d

d conversion

int type data is converted to a signed decimal string. d conversion and i conversion have the same specification.

int type

The precision specification indicates the minimum number of characters output. If the number of converted data characters is less than the precision specification, the string is prefixed with zeros. If the precision is omitted, 1 is assumed. If conversion and output of data with a value of 0 is attempted with 0 specified as the precision, nothing will be output.

i

i conversion

int type

o

o conversion

int type data is converted to an unsigned octal string.

int type

u

u conversion

int type data is converted to an unsigned decimal string.

int type

x

x conversion

int type data is converted to unsigned hexadecimal. a, b, c, d, e, and f are used as hexadecimal characters.

int type

X

X conversion

int type data is converted to unsigned hexadecimal. A, B, C, D, E, and F are used as hexadecimal characters.

int type

f

f conversion

double type data is converted to a decimal string with the format
[] ddd.ddd.

double type

The precision specification indicates the number of digits after the decimal point. When there are characters after the decimal point, at least one digit is output before the decimal point. When the precision is omitted, 6 is assumed. When 0 is specified as the precision, the decimal point and subsequent characters are not output. The output data is rounded.

e

e conversion

double type data is converted to a decimal string with the format
[] d.dddedd. At least two digits are output as the exponent.

double type

The precision specification indicates the number of digits after the decimal point. The format is such that one digit is output before the decimal point in the converted characters, and a number of digits equal to the precision are output after the decimal point. When the precision is omitted, 6 is assumed. When 0 is specified as the precision, characters after the decimal point are not output. The output data is rounded.

E

E conversion

double type data is converted to a decimal string with the format
[] d.dddEdd. At least two digits are output as the exponent.

double type

g

g conversion (or G conversion)

Whether f conversion format output or e conversion (or E conversion) format output is performed is determined by the value to be converted and the precision value that specifies the number of significant digits. Then double type data is output. If the exponent of the converted data is less than 4, or larger than the precision that indicates the number of significant digits, conversion to e (or E) format is performed.

double type

The precision specification indicates the maximum number of significant digits in the converted data.

G

double type

c

c conversion

int type data is converted to unsigned char data, with conversion to the character corresponding to that data.

int type

The precision specification is invalid.

s

s conversion

The string pointed to by pointer to char type are output up to the null character indicating the end of the string or up to the number of characters specified by the precision. (Null characters are not output. Space, horizontal tab, and new-line characters are not included in the converted string.)

Pointer to char type

The precision specification indicates the number of characters to be output. If the precision is omitted, characters are output up to, but not including, the null character in the string pointed to by the data. (Null characters are not output. Space, horizontal tab, and new-line characters are not included in the converted string.)

p

p conversion

Assuming data as a pointer, conversion is performed to a string of compiler-defined printable characters.

Pointer to
void type

The precision specification is invalid.

n

No conversion is performed.

Data is regarded as a pointer to int type, and the number of characters output so far is set in the storage area pointed to by that data.

Pointer to int type

 

%

No conversion is performed.

% is output.

None

 

 

(f) * specification for field width or precision

* can be specified as the field width or precision specification value.
In this case, the value of the parameter corresponding to the conversion specification is used as the field width or precision specification value. When this parameter has a negative field width, it is interpreted as flag '' and a positive field width. When the parameter has a negative precision, the precision is interpreted as being omitted.

 

snprintf

Converts data according to a format and outputs it to the specified area.

[Format]

#include <stdio.h>
long snprintf(char *restrict s, size_t n, const char *restrict control
[, arg]...);

[Parameters]

s Pointer to storage area to which data is to be output

n Number of characters to be output

control Pointer to string indicating format

arg, Data to be output according to format

[Return values]

Number of characters converted

[Remarks]

The snprintf function converts and edits parameter arg according to the format-representing string pointed to by control, and outputs the result to the storage area pointed to by s.

A null character is appended at the end of the converted and output string. This null character is not included in the return value (number of characters output). For details of the format specifications, see the description of the fprintf function.

 

vsnprintf

Converts data according to a format and outputs it to the specified area.

[Format]

#include <stdarg.h>
#include <stdio.h>
long vsnprintf(char *restrict s, size_t n, const char *restrict control, va_list arg)

[Parameters]

s Pointer to storage area to which data is to be output

n Number of characters to be output

control Pointer to string indicating format

arg Parameter list

[Return values]

Number of characters converted

[Remarks]

The vsnprintf function is equivalent to snprintf with arg specified instead of the variable parameters.

Initialize arg through the va_start macro before calling the vsnprintf function.

The vsnprintf function does not call the va_end macro.

 

fscanf

Inputs data from a stream input/output file and converts it according to a format.

[Format]

#include <stdio.h>
long fscanf (FILE *fp, const char *control[, ptr]...);

[Parameters]

fp File pointer

control Pointer to string indicating format

ptr,... Pointer to storage area that stores input data

[Return values]

Normal: Number of data items successfully input and converted

Abnormal: Input data ends before input data conversion is performed: EOF

[Remarks]

The fscanf function inputs data from the stream input/output file indicated by file pointer fp, converts and edits it according to the string that represents the format pointed to by control, and stores the result in the storage area pointed to by ptr.

The format specifications for inputting data are shown below.

 

Overview of Formats

The string that represents the format is made up of the following three kinds of string.

-

Space characters

If a space (' '), horizontal tab ('\t'), or new-line character ('\n') is specified, processing is performed to skip to the next non-white-space character in the input data.

-

Ordinary characters

If a character that is neither one of the space characters listed above nor % is specified, one input data character is input. The input character must match a character specified in the string that represents the format.

-

Conversion specification

A conversion specification is a string beginning with % that specifies the method of converting the input data and storing it in the area pointed to by the following parameter. The conversion specification format conforms to the following rules:

% [*] [Field width] [Converted data size] Conversion specifier

If there is no pointer to the storage area that stores input data corresponding to the conversion specification in the format, the behavior is not guaranteed. In addition, when a pointer to a storage area that stores input data remains though the format is exhausted, that pointer is ignored.

 

Description of Conversion Specifications

-

* specification

Suppresses storage of the input data in the storage area pointed to by the parameter.

-

Field width

The maximum number of characters in the data to be input is specified as a decimal number.

-

Converted data size

For d, i, o, u, x, X, e, E, and f conversions (see table 6.12), the size (short type, long type, long long type, or long double type) of the converted data is specified. In other conversions, this specification is ignored. Table 7.12 shows the types of size specification and their meanings.

Table 7.12

Converted Data Size Specification Types and Meanings

Type

Meaning

h

For d, i, o, u, x, and X conversions, specifies that the converted data is of short type.

l

For d, i, o, u, x, and X conversions, specifies that the converted data is of long type.
For e, E, and f conversions, specifies that the converted data is of double type.

L

For e, E, and f conversions, specifies that the converted data is of long double type.

ll

For d, i, o, u, x, and X conversions, specifies that the converted data is of long long type.

-

Conversion specifier

The input data is converted according to the type of conversion specified by the conversion specifier. However, processing is terminated when a white-space character is read, when a character for which conversion is not permitted is read, or when the specified field width has been exceeded.

Table 7.13

Conversion Specifiers and Conversion Methods

Conversion Specifier

Conversion Type

Conversion Method

Data Type Subject to Conversion

d

d conversion

A decimal string is converted to integer type data.

Integer type

i

i conversion

A decimal string with a sign prefixed, or a decimal string with u (U) or l (L) suffixed is converted to integer type data. A string beginning with 0x (or 0X) is interpreted as hexadecimal, and the string is converted to int type data. A string beginning with 0 is interpreted as octal, and the string is converted to int type data.

Integer type

o

o conversion

An octal string is converted to integer type data.

Integer type

u

u conversion

An unsigned decimal string is converted to integer type data.

Integer type

x

x conversion

A hexadecimal string is converted to integer type data.
There is no difference in meaning between x conversion and X conversion.

Integer type

X

X conversion

s

s conversion

Characters are converted as a single string until a space, horizontal tab, or new-line character is read. A null character is appended at the end of the string. (The string in which the converted data is set must be large enough to include the null character.)

Character type

c

c conversion

One character is input. The input character is not skipped even if it is a white-space character. To read only non-white-space characters, specify %1s. If the field width is specified, the number of characters equivalent to that specification are read. In this case, therefore, the storage area that stores the converted data needs the specified size.

char type

e

e conversion

A string indicating a floating-point number is converted to floating-point type data. There is no difference in meaning between the e conversion and E conversion, or between the g conversion and G conversion.
The input format is a floating-point number that can be represented by the strtod function.

Floating-point type

E

E conversion

f

f conversion

g

g conversion

G

G conversion

p

p conversion

A string converted by p conversion of the fprintf function is converted to pointer type data.

Pointer to void type

n

No conversion is performed.

Data input is not performed; the number of data characters input so far is set.

Integer type

[

[ conversion

A set of characters is specified after [, followed by ]. This character set defines a set of characters comprising a string. If the first character of the character set is not a circumflex (^), the input data is input as a single string until a character not in this character set is first read. If the first character is ^, the input data is input as a single string until a character which is in the character set following the ^ is first read. A null character is automatically appended at the end of the input string. (The string in which the converted data is set must be large enough to include the null character.)

Character type

%

No conversion is performed.

% is read.

None

If the conversion specifier is a letter not shown in table 6.12, the behavior is not guaranteed. For the other characters, the behavior is implementation-defined.

 

printf

Converts data according to a format and outputs it to the standard output file (stdout).

[Format]

#include <stdio.h>
long printf (const char *control[, arg]...);

[Parameters]

control Pointer to string indicating format

arg,... Data to be output according to format

[Return values]

Normal: Number of characters converted and output

Abnormal: Negative value

[Remarks]

The printf function converts and edits parameter arg according to the string that represents the format pointed to by control, and outputs the result to the standard output file (stdout).

For details of the format specifications, see the description of the fprintf function.

 

vfscanf

Inputs data from a stream input/output file and converts it according to a format.

[Format]

#include <stdarg.h>
#include <stdio.h>
long vfscanf(FILE *restrict fp, const char *restrict control, va_list arg)

[Parameters]

fp File pointer

control Pointer to wide string indicating format

arg Parameter list

[Return values]

Normal: Number of data items successfully input and converted

Abnormal: Input data ends before input data conversion is performed: EOF

[Remarks]

The vfscanf function is equivalent to fscanf with arg specified instead of the variable parameter list.

Initialize arg through the va_start macro before calling the vfscanf function.

The vfscanf function does not call the va_end macro.

 

scanf

Inputs data from the standard input file (stdin) and converts it according to a format.

[Format]

#include <stdio.h>
long scanf (const char *control[, ptr]);

[Parameters]

control Pointer to string indicating format

ptr,... Pointer to storage area that stores input and converted data

[Return values]

Normal: Number of data items successfully input and converted

Abnormal: EOF

[Remarks]

The scanf function inputs data from the standard input file (stdin), converts and edits it according to the string that represents the format pointed to by control, and stores the result in the storage area pointed to by ptr.

The scanf function returns the number of data items successfully input and converted as the return value. EOF is returned if the standard input file ends before the first conversion.

For details of the format specifications, see the description of the fscanf function.

For %e conversion, specify l for double type, and specify L for long double type. The default type is float.

 

vscanf

Inputs data from the specified storage area and converts it according to a format.

[Format]

#include <stdarg.h>
#include <stdio.h>
long vscanf(const char *restrict control, va_list arg)

[Parameters]

control Pointer to string indicating format

arg Parameter list

[Return values]

Normal: Number of data items successfully input and converted

Abnormal: Input data ends before input data conversion is performed: EOF

[Remarks]

The vscanf function is equivalent to scanf with arg specified instead of the variable parameters.

Initialize arg through the va_start macro before calling the vscanf function.

The vscanf function does not call the va_end macro.

 

sprintf

Converts data according to a format and outputs it to the specified area.

[Format]

#include <stdio.h>
long sprintf (char *s, const char *control[, arg]);

[Parameters]

s Pointer to storage area to which data is to be output

control Pointer to string indicating format

arg,... Data to be output according to format

[Return values]

Number of characters converted

[Remarks]

The sprintf function converts and edits parameter arg according to the string that represents the format pointed to by control, and outputs the result to the storage area pointed to by s.

A null character is appended at the end of the converted and output string. This null character is not included in the return value (number of characters output).

For details of the format specifications, see the description of the fprintf function.

 

sscanf

Inputs data from the specified storage area and converts it according to a format.

[Format]

#include <stdio.h>
long sscanf (const char *s, const char *control[, ptr]);

[Parameters]

s Storage area containing data to be input

control Pointer to string indicating format

ptr,... Pointer to storage area that stores input and converted data

[Return values]

Normal: Number of data items successfully input and converted

Abnormal: EOF

[Remarks]

The sscanf function inputs data from the storage area pointed to by s, converts and edits it according to the string that represents the format pointed to by control, and stores the result in the storage area pointed to by ptr.

The sscanf function returns the number of data items successfully input and converted. EOF is returned when the input data ends before the first conversion.

For details of the format specifications, see the description of the fscanf function.

 

vsscanf

Inputs data from the specified storage area and converts it according to a format.

[Format]

#include <stdarg.h>
#include <stdio.h>
long vsscanf(const char *restrict s, const char *restrict control, va_list arg)

[Parameters]

s Storage area containing data to be input

control Pointer to string indicating format

arg Parameter list

[Return values]

Normal: Number of data items successfully input and converted

Abnormal: nput data ends before input data conversion is performed: EOF

[Remarks]

The vsscanf function is equivalent to sscanf with arg specified instead of the variable parameters.

Initialize arg through the va_start macro before calling the vsscanf function.

The vsscanf function does not call the va_end macro.

 

vfprintf

Outputs a variable parameter list to the specified stream input/output file according to a format.

[Format]

#include <stdarg.h>
#include <stdio.h>
long vfprintf (FILE *fp, const char *control, va_list arg)

[Parameters]

fp File pointer

control Pointer to string indicating format

arg Parameter list

[Return values]

Normal: Number of characters converted and output

Abnormal: Negative value

[Remarks]

The vfprintf function sequentially converts and edits a variable parameter list according to the string that represents the format pointed to by control, and outputs the result to the stream input/output file indicated by fp.

The vfprintf function returns the number of data items converted and output, or a negative value when an error occurs.

Within the vfprintf function, the va_end macro is not invoked.

For details of the format specifications, see the description of the fprintf function.

Parameter arg, indicating the parameter list, must be initialized beforehand by the va_start macro (and the succeeding va_arg macro).

 

vprintf

Outputs a variable parameter list to the standard output file (stdout) according to a format.

[Format]

#include <stdarg.h>
#include <stdio.h>
long vprintf (const char *control, va_list arg)

[Parameters]

control Pointer to string indicating format

arg Parameter list

[Return values]

Normal: Number of characters converted and output

Abnormal: Negative value

[Remarks]

The vprintf function sequentially converts and edits a variable parameter list according to the string that represents the format pointed to by control, and outputs the result to the standard output file.

The vprintf function returns the number of data items converted and output, or a negative value when an error occurs.

Within the vprintf function, the va_end macro is not invoked.

For details of the format specifications, see the description of the fprintf function.

Parameter arg, indicating the parameter list, must be initialized beforehand by the va_start macro (and the succeeding va_arg macro).

 

vsprintf

Outputs a variable parameter list to the specified storage area according to a format.

[Format]

#include <stdarg.h>
#include <stdio.h>
long vsprintf (char *s, const char *control, va_list arg)

[Parameters]

s Pointer to storage area to which data is to be output

control Pointer to string indicating format

arg Parameter list

[Return values]

Normal: Number of characters converted

Abnormal: Negative value

[Remarks]

The vsprintf function sequentially converts and edits a variable parameter list according to the string that represents the format pointed to by control, and outputs the result to the storage area pointed to by s.

A null character is appended at the end of the converted and output string. This null character is not included in the return value (number of characters output).

For details of the format specifications, see the description of the fprintf function.

Parameter arg, indicating the parameter list, must be initialized beforehand by the va_start macro (and the succeeding va_arg macro).

 

fgetc

Inputs one character from a stream input/output file.

[Format]

#include <stdio.h>
long fgetc (FILE *fp);

[Parameters]

fp File pointer

[Return values]

Normal: End-of-file: EOF

Otherwise: Input character

Abnormal: EOF

[Remarks]

When a read error occurs, the error indicator for that file is set.

The fgetc function inputs one character from the stream input/output file indicated by file pointer fp.

The fgetc function normally returns the input character, but returns EOF at end-of-file or when an error occurs. At end-of-file, the end-of-file indicator for that file is set.

 

fgets

Inputs a string from a stream input/output file.

[Format]

#include <stdio.h>
char *fgets (char *s, long n, FILE *fp);

[Parameters]

s Pointer to storage area to which string is input

n Number of bytes of storage area to which string is input

fp File pointer

[Return values]

Normal: End-of-file: NULL

Otherwise: s

Abnormal: NULL

[Remarks]

The fgets function inputs a string from the stream input/output file indicated by file pointer fp to the storage area pointed to by s.

The fgets function performs input up to the (n1)th character or a new-line character, or until end-of-file, and appends a null character at the end of the input string.

The fgets function normally returns s, the pointer to the storage area to which the string is input, but returns NULL at end-of-file or if an error occurs.

The contents of the storage area pointed to by s do not change at end-of-file, but are not guaranteed when an error occurs.

 

fputc

Outputs one character to a stream input/output file.

[Format]

#include <stdio.h>
long fputc (long c, FILE *fp);

[Parameters]

c Character to be output

fp File pointer

[Return values]

Normal: Output character

Abnormal: EOF

[Remarks]

When a write error occurs, the error indicator for that file is set.

The fputc function outputs character c to the stream input/output file indicated by file pointer fp.

The fputc function normally returns c, the output character, but returns EOF when an error occurs.

 

fputs

Outputs a string to a stream input/output file.

[Format]

#include <stdio.h>
long fputs (const char *s, FILE *fp);

[Parameters]

s Pointer to string to be output

fp File pointer

[Return values]

Normal: 0

Abnormal: Nonzero

[Remarks]

The fputs function outputs the string pointed to by s up to the character preceding the null character to the stream input/output file indicated by file pointer fp. The null character indicating the end of the string is not output.

The fputs function normally returns zero, but returns nonzero when an error occurs.

 

getc

Inputs one character from a stream input/output file.

[Format]

#include <stdio.h>
long getc (FILE *fp);

[Parameters]

fp File pointer

[Return values]

Normal: End-of-file: EOF

Otherwise: Input character

Abnormal: EOF

[Remarks]

When a read error occurs, the error indicator for that file is set.

The getc function inputs one character from the stream input/output file indicated by file pointer fp.

The getc function normally returns the input character, but returns EOF at end-of-file or when an error occurs. At end-of-file, the end-of-file indicator for that file is set.

 

getchar

Inputs one character from the standard input file (stdin).

[Format]

#include <stdio.h>
long getchar (void);

[Return values]

Normal: End-of-file: EOF

Otherwise: Input character

Abnormal: EOF

[Remarks]

When a read error occurs, the error indicator for that file is set.

The getchar function inputs one character from the standard input file (stdin).

The getchar function normally returns the input character, but returns EOF at end-of-file or when an error occurs. At end-of-file, the end-of-file indicator for that file is set.

 

gets

Inputs a string from the standard input file (stdin).

[Format]

#include <stdio.h>
char *gets (char *s);

[Parameters]

s Pointer to storage area to which string is input

[Return values]

Normal: End-of-file: NULL

Otherwise: s

Abnormal: NULL

[Remarks]

The gets function inputs a string from the standard input file (stdin) to the storage area starting at s.

The gets function inputs characters up to end-of-file or until a new-line character is input, and appends a null character instead of a new-line character.

The gets function normally returns s, the pointer to the storage area to which the string is input, but returns NULL at the end of the standard input file or when an error occurs.

The contents of the storage area pointed to by s do not change at the end of the standard input file, but are not guaranteed when an error occurs.

 

putc

Outputs one character to a stream input/output file.

[Format]

#include <stdio.h>
long putc (long c, FILE *fp);

[Parameters]

c Character to be output

fp File pointer

[Return values]

Normal: Output character

Abnormal: EOF

[Remarks]

When a write error occurs, the error indicator for that file is set.

The putc function outputs character c to the stream input/output file indicated by file pointer fp.

The putc function normally returns c, the output character, but returns EOF when an error occurs.

 

putchar

Outputs one character to the standard output file (stdout).

[Format]

#include <stdio.h>
long putchar (long c);

[Parameters]

c Character to be output

[Return values]

Normal: Output character

Abnormal: EOF

[Remarks]

When a write error occurs, the error indicator for that file is set.

The putchar function outputs character c to the standard output file (stdout).

The putchar function normally returns c, the output character, but returns EOF when an error occurs.

 

puts

Outputs a string to the standard output file (stdout).

[Format]

#include <stdio.h>
long puts (const char *s);

[Parameters]

s Pointer to string to be output

[Return values]

Normal: 0

Abnormal: Nonzero

[Remarks]

The puts function outputs the string pointed to by s to the standard output file (stdout). The null character indicating the end of the string is not output, but a new-line character is output instead.

The puts function normally returns zero, but returns nonzero when an error occurs.

 

ungetc

Returns one character to a stream input/output file.

[Format]

#include <stdio.h>
long ungetc (long c, FILE *fp);

[Parameters]

c Character to be returned

fp File pointer

[Return values]

Normal: Returned character

Abnormal: EOF

[Remarks]

The ungetc function returns character c to the stream input/output file indicated by file pointer fp. Unless the fflush, fseek, or rewind function is called, this returned character will be the next input data.

The ungetc function normally returns c, which is the returned character, but returns EOF when an error occurs.

The behavior is not guaranteed when the ungetc function is called more than once without intervening fflush, fseek, or rewind function execution. When the ungetc function is executed, the current file position indicator for that file is moved back one position; however, when this file position indicator has already been positioned at the beginning of the file, its value is not guaranteed.

 

fread

Inputs data from a stream input/output file to the specified storage area.

[Format]

#include <stdio.h>
size_t fread (void *ptr, size_t size, size_t n, FILE *fp);

[Parameters]

ptr Pointer to storage area to which data is input

size Number of bytes in one member

n Number of members to be input

fp File pointer

[Return values]

When size or n is 0: 0

When size and n are both nonzero: Number of successfully input members

[Remarks]

The fread function inputs n members whose size is specified by size, from the stream input/output file indicated by file pointer fp, into the storage area pointed to by ptr. The file position indicator for the file is advanced by the number of bytes input.

The fread function returns the number of members successfully input, which is normally the same as the value of n. However, at end-of-file or when an error occurs, the number of members successfully input so far is returned, and then the return value will be less than n. The ferror and feof functions should be used to distinguish between end-of-file and error occurrence.

When the value of size or n is zero, zero is returned as the return value and the contents of the storage area pointed to by ptr do not change. When an error occurs or when only a part of the members can be input, the file position indicator is not guaranteed.

 

fwrite

Outputs data from a memory area to a stream input/output file.

[Format]

#include <stdio.h>
size_t fwrite (const void *ptr, size_t size, size_t n, FILE *fp);

[Parameters]

ptr Pointer to storage area storing data to be output

size Number of bytes in one member

n Number of members to be output

fp File pointer

[Return values]

Number of successfully output members

[Remarks]

The fwrite function outputs n members whose size is specified by size, from the storage area pointed to by ptr, to the stream input/output file indicated by file pointer fp. The file position indicator for the file is advanced by the number of bytes output.

The fwrite function returns the number of members successfully output, which is normally the same as the value of n. However, when an error occurs, the number of members successfully output so far is returned, and then the return value will be less than n.

When an error occurs, the file position indicator is not guaranteed.

 

fseek

Shifts the current read/write position in a stream input/output file.

[Format]

#include <stdio.h>
long fseek (FILE *fp, long offset, long type) ;

[Parameters]

fp File pointer

offset Offset from position specified by type of offset

type Type of offset

[Return values]

Normal: 0

Abnormal: Nonzero

[Remarks]

The fseek function shifts the current read/write position in the stream input/output file indicated by file pointer fp by offset bytes from the position specified by type (the type of offset).

The types of offset are shown in table 6.13.

The fseek function normally returns zero, but returns nonzero in response to an invalid request.

Table 7.14

Types of Offset

Offset Type

Meaning

SEEK_SET

Shifts to a position which is located offset bytes away from the beginning of the file. The value specified by offset must be zero or positive.

SEEK_CUR

Shifts to a position which is located offset bytes away from the current position in the file. The shift is toward the end of the file if the value specified by offset is positive, and toward the beginning of the file if negative.

SEEK_END

Shifts to a position which is located offset bytes forward from end-of-file. The value specified by offset must be zero or negative.

For a text file, the type of offset must be SEEK_SET and offset must be zero or the value returned by the ftell function for that file. Note also that calling the fseek function cancels the effect of the ungetc function.

 

ftell

Obtains the current read/write position in a stream input/output file.

[Format]

#include <stdio.h>
long ftell (FILE *fp);

[Parameters]

fp File pointer

[Return values]

Current file position indicator position (text file)
Number of bytes from beginning of file to current position (binary file)

[Remarks]

The ftell function obtains the current read/write position in the stream input/output file indicated by file pointer fp.

For a binary file, the ftell function returns the number of bytes from the beginning of the file to the current position. For a text file, it returns, as the position of the file position indicator, an implementation-defined value that can be used by the fseek function.

When the ftell function is used twice for a text file, the difference in the return values will not necessarily represent the actual distance in the file.

 

rewind

Shifts the current read/write position in a stream input/output file to the beginning of the file.

[Format]

#include <stdio.h>
void rewind (FILE *fp);

[Parameters]

fp File pointer

[Remarks]

The rewind function shifts the current read/write position in the stream input/output file indicated by file pointer fp, to the beginning of the file.

The rewind function clears the end-of-file indicator and error indicator for the file.

Note that calling the rewind function cancels the effect of the ungetc function.

 

clearerr

Clears the error state of a stream input/output file.

[Format]

#include <stdio.h>
void clearerr (FILE *fp);

[Parameters]

fp File pointer

[Remarks]

The clearerr function clears the error indicator and end-of-file indicator for the stream input/output file indicated by file pointer fp.

 

feof

Tests for the end of a stream input/output file.

[Format]

#include <stdio.h>
long feof (FILE *fp);

[Parameters]

fp File pointer

[Return values]

End-of-file: Nonzero

Otherwise: 0

[Remarks]

The feof function tests for the end of the stream input/output file indicated by file pointer fp.

The feof function tests the end-of-file indicator for the specified stream input/output file, and if the indicator is set, returns nonzero to indicate that the file is at its end. If the end-of-file indicator is not set, the feof function returns zero to show that the file is not yet at its end.

 

ferror

Tests for stream input/output file error state.

[Format]

#include <stdio.h>
long ferror (FILE *fp);

[Parameters]

fp File pointer

[Return values]

If file is in error state: Nonzero

Otherwise: 0

[Remarks]

The ferror function tests whether the stream input/output file indicated by file pointer fp is in the error state.

The ferror function tests the error indicator for the specified stream input/output file, and if the indicator is set, returns nonzero to show that the file is in the error state. If the error indicator is not set, the ferror function returns zero to show that the file is not in the error state.

 

perror

Outputs an error message corresponding to the error number to the standard error file (stderr).

[Format]

#include <stdio.h>
void perror (const char *s)

[Parameters]

s Pointer to error message

[Remarks]

The perror function maps errno to the error message indicated by s, and outputs the message to the standard error file (stderr).

If s is not NULL and the string pointed to by s is not a null character, the output format is as follows: the string pointed to by s followed by a colon and space, then the implementation-defined error message, and finally a new-line character.