Node:getline, Next:getdelim, Previous:String input, Up:String input

---

getline

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;
}