United States

Compaq C

# Compaq C
Language Reference Manual

Previous | Contents | Index

File Access Functions

`int fclose(FILE *stream);`

> Flushes the stream pointed to by stream and closes the associated file. Any unwritten buffered data for the stream is delivered to the host environment to be written to the file. Any unread buffered data is discarded. The stream is disassociated from the file. If the associated buffer was automatically allocated, it is deallocated. The `fclose` function returns 0 if the stream was successfully closed, or it returns `EOF` if any errors are detected.

`int fflush(FILE *stream);`

> If stream points to an output stream or an update stream in which the most recent operation was not input, the `fflush` function delivers any unwritten data to the host environment to be written to the file. Otherwise, the behavior is undefined. If stream is a null pointer, `fflush` flushes all output or update streams in which the most recent operation was not input. The `fflush` function returns 0 if the operation is successful, or it returns `EOF` if a write error occurs.

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

> Opens the file pointed to by filename and associates a stream with it. The argument mode points to a string beginning with one of the character sequences listed in Table 9-1. Additional characters can follow these sequences.

> Table 9-1 File Modes
> Mode | Description
> --- | ---
> `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

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

`FILE *freopen(const char *filename, const char *mode, FILE *stream);`

> Opens the file pointed to by filename and associates the stream pointed to by stream with it. The mode argument is used in the same way as with the `fopen` function. The `freopen` function first tries to close any file 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.
> The primary use of `freopen` is to change the file associated with a standard text stream ( `stderr` , `stdin` , or `stdout` ), because those identifiers need not be modifiable lvalues to which the value returned by the `fopen` function can be assigned.
> The `freopen` function returns a pointer to the object controlling the stream. If the open operation fails, `freopen` returns a null pointer.

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

> 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.

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

> Associates a buffer with an input or an output file. The `setvbuf` function can be used only after the stream pointed to by stream has been associated with an open file and before any other operation is performed on the stream. The argument mode determines how stream is to be buffered:
> - `IOFBF` causes I/O to be fully buffered.
> - `IOLBF` causes I/O to be line buffered.
> - `IONBF` causes I/O to be unbuffered.
> If buf is not a null pointer, the array it points to can be used instead of a buffer allocated by the `setvbuf` function. The size of the array is specified by size. The contents of the array at any time are indeterminate. The `setvbuf` function returns 0 if successful, or nonzero if an invalid value is specified for mode or if the request cannot be honored.

Formatted Input/Output Functions

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

> Writes output to the stream pointed to by stream, under control of the string pointed to by format, which specifies how subsequent arguments are converted for output. If there are an insufficient number of arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated but are otherwise ignored. The `fprintf` function returns when the end of the format string is encountered. The `fprintf` function returns the number of characters transmitted, or it returns a negative value if an output error occurred.
> See your Compaq C library routine documentation for more information.

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

> Reads input from the stream pointed to by stream, under control of the string pointed to by format, which specifies the allowable 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 an insufficient number of arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are evaluated but are otherwise ignored.
> The `fscanf` function returns the value of the macro `EOF` if an input failure occurs before any conversion. Otherwise, `fscanf` returns the number of input items assigned, which can be fewer than provided for, or even 0, if there is an early matching failure.
> See your Compaq C library routine documentation for more information.

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

> Equivalent to the `fprintf` function except that `printf` writes formatted output to the standard output stream ( `stdout` ).

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

> Equivalent to the `fscanf` function except that `scanf` reads formatted input from the standard input stream ( `stdin` ).

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

> Equivalent to the `fprintf` function except that the argument s specifies an array, rather than a stream, into which the generated output will be written. A null character is written at the end of the characters written. If copying takes place between objects that overlap, the behavior is undefined. The `sprintf` function returns the number of characters written into the array, not counting the terminating null character.

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

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

`#include <stdarg.h>`
`int vfprintf(FILE *stream, const char *format, va_list arg);`

> Equivalent to the `fprintf` function with the variable argument list replaced by arg, which must have been initialized by the `va_start` macro (and possibly subsequent `va_arg` calls). The `vfprintf` function does not invoke the `va_end` macro.

`#include <stdarg.h>`
`int vprintf(const char *format, va_list arg);`

> Equivalent to the `printf` function with the variable argument list replaced by arg, which must have been initialized by the `va_start` macro (and possibly subsequent `va_arg` calls). The `vprintf` function does not invoke the `va_end` macro.

`#include <stdarg.h>`
`int vsprintf(char *s, const char *format, va_list arg);`

> Equivalent to the `sprintf` function with the variable argument list replaced by arg, which must have been initialized by the `va_start` macro (and possibly subsequent `va_arg` calls). The `vsprintf` function does not invoke the `va_end` macro.

Character Input/Output Functions

`int fgetc(FILE *stream);`

> Returns the next character (if there is one) as an `unsigned char` converted to an `int` , from the input stream pointed to by stream, and advances the associated file-position indicator for the stream (if defined). If the stream is at end-of-file, the end-of-file indicator for the stream is set, and `fgetc` returns `EOF` . If a read error occurs, the error indicator is set, and `fgetc` returns `EOF` .

`char *fgets(char *s, int n, FILE *stream);`

> Reads at most one less than the number of characters specified by n from the stream pointed to by stream into the array pointed to by s. No additional characters are read after a new-line character (which is retained) or after the end-of-file. A null character is written immediately after the last character read into the array.
> The `fgets` function returns s if successful. If the end-of-file is encountered and no characters have been read into the array, the contents of the array remain unchanged and a null pointer is returned. If a read error occurs during the operation, the array contents are indeterminate and a null pointer is returned.

`int fputc(int c, FILE *stream);`

> Writes the character c (converted to an `unsigned char` ) to the output stream pointed to by stream, at the position indicated by the associated file position indicator for the stream (if defined), and advances the indicator appropriately. If the file cannot support positioning requests, or if the stream was opened with append mode, the character is appended to the output stream. The `fputc` function returns the character written. If a write error occurs, the error indicator for the stream is set, and `fputc` returns `EOF` .

`int fputs(const char *s, FILE *stream);`

> Writes the string pointed to by s to the stream pointed to by stream. The terminating null character is not written.
> The `fputs` function returns `EOF` if a write error occurs. Otherwise, it returns a nonnegative value.

`int getc(FILE *stream);`

> Equivalent to the `fgetc` function, but if it is implemented as a macro it can evaluate stream more than once. For this reason, the argument should never be an expression with side effects.

`int getchar(void);`

> Equivalent to the `getc` function with the argument `stdin` .

`char *gets(char *s);`

> Reads characters from the input stream pointed to by `stdin` into the array pointed to by s, until the end-of-file is encountered or a new-line character is read. Any new-line character is discarded, and a null character is written immediately after the last character read into the array.
> The `fgets` function returns s if successful. If the end-of-file is encountered and no characters have been read into the array, the contents of the array remain unchanged and a null pointer is returned. If a read error occurs during the operation, the array contents are indeterminate and a null pointer is returned.

`int putc(int c, FILE *stream);`

> Equivalent to the `fputc` function, but if it is implemented as a macro it can evaluate stream more than once. For this reason the argument should never be an expression with side effects.

`int putchar(int c);`

> Equivalent to the `putc` function with the second argument `stdout` .

`int puts(const char s);`

> Writes the string pointed to by s to the stream pointed to by `stdout` , and appends a new-line character to the output. The terminating null character is not written. The `puts` function returns `EOF` if a write error occurs. Otherwise, it returns a nonnegative value.

`int ungetc(int c, FILE *stream);`

> Pushes a character c (converted to an `unsigned char` ) back into the input stream pointed to by stream, and leaves the stream positioned before the character. The pushed back characters are returned by subsequent reads on that stream in the reverse order of their pushing. A successful intervening call to a file positioning function for that stream ( `fseek` , `fsetpos` , or `rewind` ) discards any pushed-back characters.
> One pushback is guaranteed, even if there has been no previous activity on the file. The `ungetc` function returns the converted pushed-back character, or it returns `EOF` if the operation fails.

Direct Input/Output Functions

`size_t fread(void *ptr, size_t size, size_t nmemb, FILE *stream);`

> Reads into the array pointed to by ptr up to nmemb elements of size size from the stream pointed to by stream. The file-position indicator for the stream (if defined) is advanced by the number of characters successfully read. If an error occurs, the resulting value of the file-position indicator for the stream is indeterminate. If a partial element is read, its value is indeterminate.
> The `fread` function returns the number of elements successfully read, which may be less than nmemb if a read error or end-of-file is encountered. If size or nmemb is 0, `fread` returns 0, and the contents of the array and the state of the stream are unchanged.

`size_t fwrite(const void *ptr, size_t size, size_t nmemb, FILE *stream);`

> Writes from the array pointed to by ptr up to nmemb elements of size size to the stream pointed to by stream. The file-position indicator for the stream (if defined) is advanced by the number of characters successfully written. If an error occurs, the resulting value of the file-position indicator for the stream is indeterminate.
> The `fwrite` function returns the number of elements successfully written, which is less than nmemb only if a write error is encountered.

File Positioning Functions

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

> Stores the current value of the file-position indicator for the stream pointed to by stream into the object pointed to by pos. The value stored contains unspecified information used by the `fsetpos` function to return the stream to its position at the time of the call to `fgetpos` .
> If successful, the `fgetpos` function returns 0. On failure, `fgetpos` returns nonzero and stores an implementation-defined positive value in `errno` .

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

> Sets the file-position indicator to the specified byte offset in 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, which is one of the following:
> - The beginning of the file if whence is `SEEK_SET`
> - The current value of the file-position indicator if whence is `SEEK_CUR`
> - The end of the file if whence is `SEEK_END`
> For a text stream, either offset is 0 or it is a value returned by an earlier call to the `ftell` function on the same stream and whence is `SEEK_SET` .
> A successful call to `fseek` clears the end-of-file indicator for the stream and reverses any effects of the `ungetc` function on the same stream. After an `fseek` call, the next operation on an update stream can be either input or output. The `fseek` function returns nonzero only for a request that cannot be satisfied.

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

> Sets the file-position indicator for the stream pointed to by stream according to the value of the object pointed to by pos, which is a value obtained from an earlier call to the `fgetpos` function on the same stream.
> A successful call to `fsetpos` clears the end-of-file indicator for the stream and reverses any effects of the `ungetc` function on the same stream. After an `fsetpos` call, the next operation on an update stream can be either input or output.
> If successful, the `fsetpos` function returns 0. On failure, `fsetpos` returns nonzero and stores an implementation-defined positive value in `errno` .

`long int ftell(FILE *stream);`

> Gets 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 used by the `fseek` function for returning the file-position indicator for the stream to its position at the time of the call to `ftell` . The difference between two such return values is not necessarily a meaningful measure of the number of characters written or read.
> If successful, the `ftell` function returns the current value of the file-position indicator for the stream. On failure, `ftell` returns `--1L` and stores an implementation-defined positive value in `errno` .

`void rewind(FILE *stream);`

> Sets the file-position indicator for the stream pointed to by stream to the beginning of the file. It is equivalent to the following, except that the error indicator for the stream is also cleared:

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

> The `rewind` function returns no value.

Error-Handling Functions

`void clearerr(FILE *stream);`

> Clears the end-of-file and error indicators for the stream pointed to by stream. The `clearerr` function returns no value.

`int feof(FILE *stream);`

> Tests the end-of-file indicator for the stream pointed to by stream. The `feof` function returns nonzero only if the end-of-file indicator is set for `stream` .

`int ferror(FILE *stream);`

> Tests the error indicator for the stream pointed to by stream. The `ferror` function returns nonzero only if the end-of-file indicator is set for `stream` .

`void perror(const char *s);`

> Maps the error number in the integer expression `errno` to an error message. It writes the following sequence of characters to the standard error stream:
> 1. The string pointed to by s followed by a colon (:) and a space (if s is not a null pointer and the character pointed to by s is not the null character)
> 2. 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. The `perror` function returns no value.

Previous | Next | Contents | Index

privacy and legal statement