# getdelim

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           getdelim, getline — read a delimited record from _stream_
    


## SYNOPSIS



           #include <stdio.h>
    
           ssize_t getdelim(char **restrict _lineptr_ , size_t *restrict _n_ ,
               int _delimiter_ , FILE *restrict _stream_);
           ssize_t getline(char **restrict _lineptr_ , size_t *restrict _n_ ,
               FILE *restrict _stream_);
    


## DESCRIPTION



           The _getdelim_() function shall read from _stream_ until it encounters
           a character matching the _delimiter_ character. The _delimiter_
           argument is an **int** , the value of which the application shall
           ensure is a character representable as an **unsigned char** of equal
           value that terminates the read process. If the _delimiter_ argument
           has any other value, the behavior is undefined.
    
           The application shall ensure that _*lineptr_ is a valid argument
           that could be passed to the _free_() function. If _*n_ is non-zero,
           the application shall ensure that _*lineptr_ either points to an
           object of size at least _*n_ bytes, or is a null pointer.
    
           If _*lineptr_ is a null pointer or if the object pointed to by
           _*lineptr_ is of insufficient size, an object shall be allocated as
           if by _malloc_() or the object shall be reallocated as if by
           _realloc_(), respectively, such that the object is large enough to
           hold the characters to be written to it, including the terminating
           NUL, and _*n_ shall be set to the new size. If the object was
           allocated, or if the reallocation operation moved the object,
           _*lineptr_ shall be updated to point to the new object or new
           location.  The characters read, including any delimiter, shall be
           stored in the object, and a terminating NUL added when the
           delimiter or end-of-file is encountered.
    
           The _getline_() function shall be equivalent to the _getdelim_()
           function with the _delimiter_ character equal to the <newline>
           character.
    
           The _getdelim_() and _getline_() functions may mark the last data
           access timestamp of the file associated with _stream_ for update.
           The last data access timestamp shall be marked for update by the
           first successful execution of _fgetc_(), _fgets_(), _fread_(), _fscanf_(),
           _getc_(), _getchar_(), _getdelim_(), _getline_(), _gets_(), or _scanf_() using
           _stream_ that returns data not supplied by a prior call to _ungetc_().
    


## RETURN VALUE



           Upon successful completion, the _getline_() and _getdelim_() functions
           shall return the number of bytes written into the buffer,
           including the delimiter character if one was encountered before
           EOF, but excluding the terminating NUL character. If the end-of-
           file indicator for the stream is set, or if no characters were
           read and the stream is at end-of-file, the end-of-file indicator
           for the stream shall be set and the function shall return -1.  If
           an error occurs, the error indicator for the stream shall be set,
           and the function shall return -1 and set _errno_ to indicate the
           error.
    


## ERRORS



           For the conditions under which the _getdelim_() and _getline_()
           functions shall fail and may fail, refer to fgetc(3p).
    
           In addition, these functions shall fail if:
    
           **EINVAL** _lineptr_ or _n_ is a null pointer.
    
           **ENOMEM** Insufficient memory is available.
    
           These functions may fail if:
    
           **EOVERFLOW**
                  The number of bytes to be written into the buffer,
                  including the delimiter character (if encountered), would
                  exceed {SSIZE_MAX}.
    
           _The following sections are informative._
    


## EXAMPLES



               #include <stdio.h>
               #include <stdlib.h>
    
               int main(void)
               {
                   FILE *fp;
                   char *line = NULL;
                   size_t len = 0;
                   ssize_t read;
                   fp = fopen("/etc/motd", "r");
                   if (fp == NULL)
                       exit(1);
                   while ((read = getline(&line, &len, fp)) != -1) {
                       printf("Retrieved line of length %zu :\n", read);
                       printf("%s", line);
                   }
                   if (ferror(fp)) {
                       /* handle error */
                   }
                   free(line);
                   fclose(fp);
                   return 0;
               }
    


## APPLICATION USAGE



           Setting _*lineptr_ to a null pointer and _*n_ to zero are allowed and
           a recommended way to start parsing a file.
    
           The _ferror_() or _feof_() functions should be used to distinguish
           between an error condition and an end-of-file condition.
    
           Although a NUL terminator is always supplied after the line, note
           that _strlen_(*_lineptr_) will be smaller than the return value if the
           line contains embedded NUL characters.
    


## RATIONALE



           These functions are widely used to solve the problem that the
           _fgets_() function has with long lines. The functions automatically
           enlarge the target buffers if needed. These are especially useful
           since they reduce code needed for applications.
    


## FUTURE DIRECTIONS



           None.
    


* * *