C getline : Reading from a Stream

The getline function is used to read a stream. getline uses parameters that require you to use the stdio.h header file (included in the standard C library). One of the variables within the stdio.h library that will be used is the size_t variable, which will be discussed in the “Memory” section. The stdio.h library also includes macros that will be used with the getline function, such as the NULL (used for the null pointer value) and the EOFM (used for indicating when the end of file has been reached) macros. Essentially, macros include stored code that can be used or referenced without requiring a function call in order to run the code. When you use the stdio.h header, you do not have to focus on the background processes.

Do you want to learn more about the variables and header files found in the C programming language? Take a class at Udemy.com.

The basic syntax of the getline function includes a pointer (for the storage of the string characters), specification for the size of the stream read (uses the size_t variable), and a pointer to the FILE object (for the location of the stream being read). The following is an example:

getline (&your_string, &nbytes, stdin);

The example above includes a pointer parameter called &your_string, assume you have defined &your_string and therefore, memory is allocated for the pointer of your string. The second parameter in the example is called &nbytes, assume you have defined &nbytes and that you have indicated the number of bytes to be used for the stream. The last parameter is stdin because, in this case, the source of the file or characters being read will be from user input. In order for your program to use the parameters set for your getline function, you will have to ensure that the parameters have been defined.

Why should you use getline?

You should use getline as opposed to other functions such as gets and fgets, when reading a string because getline is a more accurate method. One reason that getline is more accurate is because it does not stop reading a line when it detects a null character. It continues to read up to and including the null character. Additionally, the block of memory that will be used for the string can be reallocated in order to allocate enough space for a string.

Memory

Earlier, it was mentioned that the size_t variable is used for the getline function. The size_t variable is used to indicate the number of bytes of memory that will be used for a stream. When you define the first parameter for getline, you are defining the pointer to a block of memory to be allocated. A great feature of the getline function is that the block of memory can automatically be reallocated in order to allow enough memory allocation for your stream; C can utilize the malloc (memory allocation) and realloc (reallocation) functions for memory handling. In your example for using getline, your function will read a stream via input and because the input of a user cannot be pre-determined, the input data will be dynamic.

Explore C more in-depth with a class at Udemy.com.

getline Example

As stated earlier, in order to use your getline function [ getline (&your_string, &nbytes, stdin); ], you need to ensure that the parameters are defined. In your main method, you declare (or define) the variables.

#include <stdio.h>  /*this is the stdio header file that you want to include in order to use variables and macros that will be referenced in your program*/
int main ()  /*your main method*/
{
int memory_read;    /*this will be used as the variable for the value of the bytes read from the getline function*/
int nbytes = 200;    /*this is the variable for the number of bytes initially allocated for your stream*/
char *your_string;    /*this is the variable for the character file object used for your stream*/
puts (“Enter stream, or line of text, here:”);    /*prompt for user to enter text*/
your_string = (char *) malloc (nbytes + 1);    /*note the char cast operator as the pointer used will be a character pointer and also note that it’s added 1 to nbytes for the malloc function; the last character read by getline should be a null character and it’s added the one to account for the last null character that will be read*/
memory_read = getline (&your_string, &nbytes, stdin);     /*the value of memory read will be determined by the return of your getline function*/
if (memory_read == -1)  /* if a character is not read by getline, then -1 will be returned*/
{
puts (“Error: only EOF without text read”);    /*displays error no bytes had been read, hence, if -1 had been returned*/
}
else   /*if -1 had not been returned*/
{
puts (your_string);   /*displays string that had been entered*/
}
return 0;
}

The following is the example above displayed without comments:

#include <stdio.h>
int main()
{
int memory_read;
int nbytes = 200;
char *your_string;
puts (“Enter stream, or line of text, here:”);
your_string = (char *) malloc (nbytes + 1);
memory_read = getline (&your_string, &nbytes, stdin);
if (memory_read == -1)
{
puts (“Error : only EOF without text read”);
}
else
{
puts (your_string);
}
return 0;
}

Return To Memory

It should be emphasized that when you the malloc function with the getline function, the memory block reserved, or allocated, for your stream is referenced using a pointer. In your example, the char cast operator is used to indicate that the type cast of a character will be used to cast the value returned from the malloc function. If you wanted to use the realloc function for your example, then the following line of code could be used:

your_string = (char *) realloc (your_string, 501);   /*this would reallocate a block for 500 bytes*/

Conclusion

getline is a function that can be used to read a stream via input or from a different file location. There are different methods that may be used along with getline that will help you customize the function. In addition to providing different options; getline can be used to decrease the likelihood of errors as memory block usage can be reallocated to ensure all characters will be read, the first null character is also read after characters are read to increase that chance of all characters in a stream will be read, and errors can be detected by using an if-then-else statement that can enable you to perform an action if -1 is returned.

Want to develop iOS apps in C? Take a class at Udemy.com.