C h a p t e r 2 5 : T h e C - B a s e d I / O F u n c t i o n s
703
The fgetpos( ) function stores the current value of the file position indicator in the object pointed to by position. The object pointed to by position must be of type fpos_t.
The value stored there is useful only in a subsequent call to fsetpos( ).
If an error occurs, fgetpos( ) returns nonzero; otherwise it returns zero.
Related functions are fsetpos( ), fseek( ), and ftell( ).
fgets
#include <cstdio> char *fgets(char * str, int num, FILE *stream);
The fgets( ) function reads up to num-1 characters from stream and places them into the character array pointed to by str. Characters are read until either a newline or an
EOF
is received or until the specified limit is reached. After the characters have been read, a null is placed in the array immediately after the last character read. A newline character will be retained and will be part of the array pointed to by str.
If successful, fgets( ) returns str; a null pointer is returned upon failure. If a read error occurs, the contents of the array pointed to by str are indeterminate. Because a null pointer will be returned when either an error has occurred or when the end of the file is reached, you should use feof( ) or ferror( ) to determine what has actually happened.
Related functions are fputs( ), fgetc( ), gets( ), and puts( ).
fopen
#include <cstdio>
FILE *fopen(const char * fname, const char *mode);
The fopen( ) function opens a file whose name is pointed to by fname and returns the stream that is associated with it. The type of operations that will be allowed on the file are defined by the value of mode. The legal values for mode are shown in Table 25-1.
The filename must be a string of characters comprising a valid filename as defined by the operating system and may include a path specification if the environment supports it.
If fopen( ) is successful in opening the specified file, a FILE pointer is returned.
If the file cannot be opened, a null pointer is returned.
704
C + + : T h e C o m p l e t e R e f e r e n c e
Mode
"r"
"w"
"a"
"rb"
"wb"
"ab"
"r+"
"w+"
"a+"
"rb+" or "r+b"
"wb+" or "w+b"
"ab+" or "a+b"
Meaning
Open text file for reading.
Create a text file for writing.
Append to text file.
Open binary file for reading.
Create binary file for writing.
Append to a binary file.
Open text file for read/write.
Create text file for read/write.
Open text file for read/write.
Open binary file for read/write.
Create binary file for read/write.
Open binary file for read/write.
Table 25-1.
The Legal Values for the mode Parameter of fopen( )
As the table shows, a file may be opened in either text or binary mode. In text mode, some character translations may occur. For example, newlines may be converted into carriage return/linefeed sequences. No such translations occur on binary files.
The correct method of opening a file is illustrated by this code fragment:
FILE *fp; if ((fp = fopen("test", "w"))==NULL) { printf("Cannot open file.\n"); exit(1);
}
This method detects any error in opening a file, such as a write-protected or a full disk, before attempting to write to it.
If you use fopen( ) to open a file for output, any preexisting file by that name will be erased and a new file started. If no file by that name exists, one will be created.
