Next: Unreading, Previous: Character Input, Up: I/O on Streams
Since many programs interpret input on the basis of lines, it is convenient to have functions to read a line of text from a stream.
Standard C has functions to do this, but they aren't very safe: null
characters and even (for gets) long lines can confuse them. So
the GNU library provides the nonstandard getline function that
makes it easy to read lines reliably.
Another GNU extension, getdelim, generalizes getline. It
reads a delimited record, defined as everything through the next
occurrence of a specified delimiter character.
All these functions are declared in stdio.h.
This function reads an entire line from stream, storing the text (including the newline and a terminating null character) in a buffer and storing the buffer address in
*lineptr.Before calling
getline, you should place in*lineptr the address of a buffer*n bytes long, allocated withmalloc. If this buffer is long enough to hold the line,getlinestores the line in this buffer. Otherwise,getlinemakes the buffer bigger usingrealloc, storing the new buffer address back in*lineptr and the increased size back in*n. See Unconstrained Allocation.If you set
*lineptr to a null pointer, and*n to zero, before the call, thengetlineallocates the initial buffer for you by callingmalloc.In either case, when
getlinereturns,*lineptr is achar *which points to the text of the line.When
getlineis successful, it returns the number of characters read (including the newline, but not including the terminating null). This value enables you to distinguish null characters that are part of the line from the null character inserted as a terminator.This function is a GNU extension, but it is the recommended way to read lines from a stream. The alternative standard functions are unreliable.
If an error occurs or end of file is reached without any bytes read,
getlinereturns-1.
This function is like
getlineexcept that the character which tells it to stop reading is not necessarily newline. The argument delimiter specifies the delimiter character;getdelimkeeps reading until it sees that character (or end of file).The text is stored in lineptr, including the delimiter character and a terminating null. Like
getline,getdelimmakes lineptr bigger if it isn't big enough.
getlineis in fact implemented in terms ofgetdelim, just like this:ssize_t getline (char **lineptr, size_t *n, FILE *stream) { return getdelim (lineptr, n, '\n', stream); }
The
fgetsfunction reads characters from the stream stream up to and including a newline character and stores them in the string s, adding a null character to mark the end of the string. You must supply count characters worth of space in s, but the number of characters read is at most count − 1. The extra character space is used to hold the null character at the end of the string.If the system is already at end of file when you call
fgets, then the contents of the array s are unchanged and a null pointer is returned. A null pointer is also returned if a read error occurs. Otherwise, the return value is the pointer s.Warning: If the input data has a null character, you can't tell. So don't use
fgetsunless you know the data cannot contain a null. Don't use it to read files edited by the user because, if the user inserts a null character, you should either handle it properly or print a clear error message. We recommend usinggetlineinstead offgets.
The
fgetwsfunction reads wide characters from the stream stream up to and including a newline character and stores them in the string ws, adding a null wide character to mark the end of the string. You must supply count wide characters worth of space in ws, but the number of characters read is at most count − 1. The extra character space is used to hold the null wide character at the end of the string.If the system is already at end of file when you call
fgetws, then the contents of the array ws are unchanged and a null pointer is returned. A null pointer is also returned if a read error occurs. Otherwise, the return value is the pointer ws.Warning: If the input data has a null wide character (which are null bytes in the input stream), you can't tell. So don't use
fgetwsunless you know the data cannot contain a null. Don't use it to read files edited by the user because, if the user inserts a null character, you should either handle it properly or print a clear error message.
The
fgets_unlockedfunction is equivalent to thefgetsfunction except that it does not implicitly lock the stream.This function is a GNU extension.
The
fgetws_unlockedfunction is equivalent to thefgetwsfunction except that it does not implicitly lock the stream.This function is a GNU extension.
The function
getsreads characters from the streamstdinup to the next newline character, and stores them in the string s. The newline character is discarded (note that this differs from the behavior offgets, which copies the newline character into the string). Ifgetsencounters a read error or end-of-file, it returns a null pointer; otherwise it returns s.Warning: The
getsfunction is very dangerous because it provides no protection against overflowing the string s. The GNU library includes it for compatibility only. You should always usefgetsorgetlineinstead. To remind you of this, the linker (if using GNUld) will issue a warning whenever you usegets.