Previous | Table of Contents | Next |
gets, fgets
char *gets(char *buf) char *fgets(char *buf, int n, FILE *fp)
fgets reads a line of text (terminated by \n) from the stream fp, and stores the text as a string (including the \n and a terminating \0) to the character array pointed to by buf. The size of the array is assumed to be n; if the line is longer than n-2 characters (not counting the newline), some characters are left unread. (The stored string is terminated with \0 in any case.)
gets is roughly equivalent to fgets, except that it implicitly reads from stdin, does not place the \n in the string pointed to by buf, and does not permit the array size to be specified. Because of the lack of an array size specification, gets cannot be used safely and should be avoided.
Both gets and fgets return the string read (i.e., they return the value of their buf argument), or NULL on end-of-file or error. Notice that if the input happens to contain null (\0) characters, the string will seem to be prematurely terminated.
puts, fputs
int puts(char *str) int fputs(char *str, FILE *fp)
fputs writes the string pointed to by str to the stream fp. puts writes the string pointed to by str, along with a trailing \n, to stdout. Both functions return a nonnegative value, or EOF if an error occurs.
fread
size_t fread(void *buf, size_t elsize, size_t n, FILE *fp)
fread attempts to read a block of characters from the stream fp into the buffer pointed to by buf, with no attempt being made to group characters into lines with \n or strings with \0. Up to n*elsize bytes are read, under the assumption that they represent n data elements, each of size elsize. (Therefore, to read characters, it is most appropriate to pass elsize as 1 and n as the number of characters desired.) The return value is the number of elements (i.e., of size elsize) successfully read, or EOF on end-of-file or error.
fwrite
size_t fwrite(void *buf, size_t elsize, size_t n, FILE *fp)
fwrite attempts to write a block of characters (not necessarily terminated by \0) from the buffer pointed to by buf to the stream fp. The number of bytes written is n*elsize, under the assumption that they represent n data elements, each of size elsize. (Therefore, to write characters, it is most appropriate to pass elsize as 1 and n as the number of characters.) The return value is the number of elements successfully written.
ungetc
int ungetc(int c, FILE *fp)
ungetc attempts to push the character with the value c back onto the input stream fp, where it will be available for reading by the next input call. One characters worth of push-back is guaranteed. The return value is the character pushed back, or EOF if an error occurs.
ungetc is useful in lexical analyzers and the like, when it is not possible to determine the end of a particular token until one character past it has been read. For example, here is a code fragment that reads a string of digits from a stream and returns their decimal value, but leaves the first nondigit character in the input stream:
int n = 0; int c; while((c = getc(fp)) >= 0 && c <= 9) n = 10 * n + (c - 0); ungetc(c, fp);
3.10.1.3. Repositioning Streams
ftell
long int ftell(FILE *fp)
ftell returns a long integer representing the current position of the stream fp. This value may be passed to the fseek function to return the stream to the same point. For binary streams (that is, streams opened with the b modifier), the value is the offset from the beginning of the file, in bytes.
If the stream position might be too large to be represented in a long int, use fgetpos (see section 3.10.1.3) instead.
fseek, rewind
int fseek(FILE *fp, long int pos, int whence) void rewind(FILE *fp)
fseek repositions the stream fp to the position pos, according to the whence argument.
If whence is the value SEEK_SET (defined in <stdio.h>) and pos is 0, the stream is rewound to the beginning. If whence is SEEK_SET and pos is a value returned by ftell, the stream is set to that position. If whence is SEEK_SET and fp is a binary stream, the stream is set to a position pos bytes from the beginning.
If whence is the value SEEK_CUR and pos is 0, the streams position is unchanged. If whence is SEEK_CUR and fp is a binary stream, the stream is set to a position pos bytes forward or backward (depending on the sign of pos) from the beginning.
If whence is the value SEEK_END and pos is 0, the stream is set to its end-of-file position. If whence is SEEK_CUR, fp is a binary stream, and the implementation permits it, the stream is set to a position pos bytes forward or backward (depending on the sign of pos) from the end of the file.
If the request cannot be satisfied, a nonzero value is returned.
Except for the return value, rewind(fp) is equivalent to fseek(fp, 0, SEEK_SET).
When pos might be too large to be represented in a long int, use fsetpos (see section 3.10.1.3) instead.
fgetpos, fsetpos
int fgetpos(FILE *fp, fpos_t *pos) int fsetpos(FILE *fp, const fpos_t *pos)
fgetpos records the current position of the stream fp by storing it in the fpos_t object pointed to by pos, in a manner potentially able to record larger positions than would fit in a long int.
fsetpos sets the position of the stream fp to the fpos_t value pointed to by pos, which must be a value previously recorded by fgetpos.
Both functions return 0 if they are successful.
Previous | Table of Contents | Next |