The getline function is the preferred method for reading lines of
text from a stream, including standard input. The other standard
functions, including gets, fgets, and scanf, are
too unreliable. (Doubtless, in some programs you will see code that uses
these unreliable functions, and at times you will come across compilers
that cannot handle the safer getline function. As a
professional, you should avoid unreliable functions and any compiler
that requires you to be unsafe.)
The getline function reads an entire line from a stream, up to
and including the next newline character. It takes three parameters.
The first is a pointer to a block allocated with malloc or
calloc. (These two functions allocate computer memory for the
program when it is run. See Memory allocation, for more
information.) This parameter is of type char **; it will
contain the line read by getline when it returns. The second
parameter is a pointer to a variable of type size_t; this
parameter specifies the size in bytes of the block of memory pointed to
by the first parameter. The third parameter is simply the stream from
which to read the line.
The pointer to the block of memory allocated for getline is merely
a suggestion. The getline function will automatically enlarge
the block of memory as needed, via the realloc function, so there is
never a shortage of space -- one reason why getline is so safe.
Not only that, but getline will also tell you the new size of the block
by the value returned in the second parameter.
If an error occurs, such as end of file being reached without reading
any bytes, getline returns -1. Otherwise, the first parameter
will contain a pointer to the string containing the line that was read,
and getline returns the number of characters read (up to and
including the newline, but not the final null character). The return
value is of type ssize_t.
Although the second parameter is of type pointer to string (char
**), you cannot treat it as an ordinary string, since it may contain
null characters before the final null character marking the end of the
line. The return value enables you to distinguish null characters that
getline read as part of the line, by specifying the size of the
line. Any characters in the block up to the number of bytes specified
by the return value are part of the line; any characters after that
number of bytes are not.
Here is a short code example that demonstrates how to use getline
to read a line of text from the keyboard safely. Try typing more than
100 characters. Notice that getline can safely handle your line
of input, no matter how long it is. Also note that the puts
command used to display the line of text read will be inadequate if the
line contains any null characters, since it will stop displaying text at
the first null, but that since it is difficult to enter null characters
from the keyboard, this is generally not a consideration.
#include <stdio.h>
int main()
{
int bytes_read;
int nbytes = 100;
char *my_string;
puts ("Please enter a line of text.");
/* These 2 lines are the heart of the program. */
my_string = (char *) malloc (nbytes + 1);
bytes_read = getline (&my_string, &nbytes, stdin);
if (bytes_read == -1)
{
puts ("ERROR!");
}
else
{
puts ("You typed:");
puts (my_string);
}
return 0;
}
