getline, getdelim Subroutines

Purpose

Reads a delimited record from a stream.

Library

Standard Library (libc.a)

Syntax

#include <stdio.h>
ssize_t getdelim(char **lineptr, size_t *n, int delimiter, FILE *stream);  
ssize_t getline(char **lineptr, size_t *n, FILE *stream);

Description

The getdelim function reads from stream until it encounters a character matching the delimiter character. The delimiter argument is an int, the value of which the application will 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 will 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 points to an object of at least *n bytes.

The getline() function is equivalent to the getdelim() function with delimiter character equal to the '\n' character.

Return Values

Upon successful completion, the getdelim() function will return the number of characters written into the buffer, including the delimiter character if one was encountered before EOF. Otherwise, it returns -1 and set the errno to indicate the error.

Error Codes

The function may fail if:

Item Description
[EINVAL] lineptr or n are null pointers
[ENOMEM] Insufficient memory is available.
[EINVAL] Stream is not a valid file descriptor.
[EOVERFLOW] More than {SSIZE_MAX} characters were read without encountering the delimiter character.