GETDELIM(3)

NAME
getline, getdelim - read a delimited record from a stream

SYNOPSIS
#include <stdio.h>

ssize_t getdelim( char **linebuf, size_t *n, int delim, FILE *stream );
ssize_t getline( char **linebuf, size_t *n, FILE *stream );

Feature Test Macro Requirements for libmingwex:

getdelim(), getline():
    Available since libmingwex version 3.22:
    _POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700

DESCRIPTION
The getdelim() function reads data from stream, until either a character entity matching delim, or EOF is encountered; the data so read, including the delim character if present, is stored into the buffer referenced by the pointer at * linebuf, and is NUL terminated.

The getline() function is a special case of getdelim(), with the delim argument implicitly specified as the POSIX newline character, '\n'.

The linebuf argument must be a reference to a pointer which is safe to pass to free(); either a NULL pointer, or a pointer to a buffer of size as indicated by * n, allocated by malloc(). Passing a value of NULL in * linebuf, with a value of zero in * n, is both allowed, and recommended as a mechanism for requesting allocation of a default buffer.

The delim argument is specified as an int; it must be passed a value which is representable as an unsigned char, otherwise the behaviour is undefined.

If *linebuf is initially passed as a NULL pointer, then getdelim() or getline() will call malloc(), in an attempt to allocate *n bytes, or an arbitrarily sized smaller default buffer, if such an allocation is not achievable. In either case, *linebuf and *n will be updated to reflect the allocated buffer location, and the actual size allocated.

If, at any time during collection of the input record, the buffer referenced by *linebuf becomes too small to store the record, it will be expanded as necessary, and both *linebuf and *n will be adjusted to reflect the change in allocation.

RETURN VALUE
On successful completion, getline() and getdelim() return the number of characters stored into the buffer at * linebuf, including the delim character if this was encountered before EOF, but excluding the terminating NUL character.

If no characters were read, and stream is at end-of-file, getline() and getdelim() return -1, and the end-of-file indicator is set for stream.

If an error occurs, getline() and getdelim() set errno, as indicated under the heading ERROR CONDITIONS below, and return -1.

ERROR CONDITIONS
getline() and getdelim may fail for any of the reasons described as failure conditions for fgetc(); when any such error occurs, errno is left as set by fgetc(), and getline() or getdelim() returns -1.

In addition to fgetc() failure conditions, getline() and getdelim() may fail, returning -1 after setting errno to indicate occurrence of any of the following errors:

    EINVAL
        linebuf or n is NULL.

    EBADF
        stream is a NULL pointer, or otherwise is not a valid stream opened for reading, as determined by fgetc().

    ENOMEM
        An attempt to allocate a buffer, or to expand the buffer referenced by * linebuf, was unsuccessful.

    ERANGE
        More than SSIZE_MAX characters were read, without finding delim. (Note that POSIX specifies that errno should be set to EOVERFLOW for this error condition; see heading CAVEATS AND BUGS below, for the rationale for the use of ERANGE in this implementation).

CONFORMING TO
Originally implemented as GNU extension functions, both getline() and getdelim() were adopted into POSIX.1-2008; implementations conforming to this POSIX standard have been integrated into libmingwex from version 3.22 onwards.

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

CAVEATS AND BUGS
A return value of -1 may indicate that stream is already at end-of-file when getline() or getdelim() is called, or it may indicate an error condition; use ferror() or feof() to distinguish error and end-of-file conditions.

The return type of ssize_t can accommodate a maximum character count of SSIZE_MAX, and thus, the return value will overflow if getline() or getdelim() reads SSIZE_MAX characters without encountering a line delimiter; for this overflow condition, POSIX.1-2008 stipulates an errno condition code of EOVERFLOW . However, MSVCRT.DLL provides no significant interpretation for an arbitrarily assigned EOVERFLOW errno code. Thus, this implementation of getline() and getdelim() substitutes the semantically similar, (but not semantically identical), ERANGE errno code for EOVERFLOW, to ensure that MSVCRT.DLL's strerror() can return an acceptable description for this error condition.

SEE ALSO
Please refer to Microsoft's documentation, on MSDN, for standard I/O streams, fgetc(), ferror(), feof(), malloc(), free(), strerror(), and errno.

AUTHOR
This manpage was written by Keith Marshall, <keithmarshall@users.sourceforge.net>, to document the getline() and getdelim() functions as they have been implemented for the MinGW.org Project. It may be copied, modified and redistributed, without restriction of copyright, provided this acknowledgement of contribution by the original author remains unchanged.