rose_getline

Reads a line of text from a stream.

Synopsis

Declared in <rose_getline.h>

[[visibility]]
ssize_t
rose_getline(
    char** lineptr,
    size_t* n,
    FILE* stream);

Description

This function reads an entire line from stream, storing the text (including the newline and a terminating null character) in a buffer and storing the buffer address in lineptr. This documentation is copied from the GNU source code with a few formatting modifications and name changes. ROSE provides its own getline‐style implementation for portability.

Before calling rose_getline(), you should place in lineptr the address of a buffer n bytes long, allocated with malloc(). If this buffer is long enough to hold the line, rose_getline() stores the line in this buffer. Otherwise, rose_getline() makes the buffer bigger using realloc(), storing the new buffer address back in lineptr and the increased size back in n.

If you set lineptr to a null pointer, and n to zero, before the call, then rose_getline() allocates the initial buffer for you by calling malloc().

In either case, when rose_getline() returns, lineptr points to the text of the line.

When rose_getline() is successful, it returns the number of characters read (including the newline, but not including the terminating null). This value enables you to distinguish NUL characters that are part of the line from the NUL character inserted as a terminator.

This is the recommended way to read lines from a stream. The alternative standard functions are unreliable.

If an error occurs or end of file is reached without any bytes read, getline() returns ‐1.

@{

Return Value

Number of characters read, or ‐1 on EOF/error.

Parameters

Name	Description
lineptr	Pointer to the buffer pointer (may be null to allocate).
n	Pointer to the buffer length in bytes.
stream	Input stream.

Created with MrDocs