GETLINE(3)

ИМЯ
getline, getdelim - разделяет входные данные на строки

ОБЗОР
#include <stdio.h>

ssize_t getline(char **lineptr, size_t *n, FILE *stream);

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

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

getline(), getdelim():
    Начиная с glibc 2.10:
        _POSIX_C_SOURCE >= 200809L
    До glibc 2.10:
        _GNU_SOURCE

ОПИСАНИЕ
Функция getline() считывает целую строку из stream, сохраняет адрес буфера с текстом в *lineptr. Буфер завершается null и включает символ новой строки, если был найден разделитель для новой строки.

Если *lineptr равно NULL и *n равно 0 перед вызовом, то getline() выделит буфер для хранения строки. Этот буфер должен быть высвобожден программой пользователя, даже если getline() завершилась с ошибкой.

Как альтернатива, перед вызовом getline(), *lineptr может содержать указатель на буфер, выделенный с помощью malloc(3) размером *n байтов. Если буфер недостаточно велик для размещения строки, то getline() изменяет размер буфера с помощью realloc(3), обновляя *lineptr и *n при необходимости.

В любом случае при успешном выполнении вызова *lineptr и *n будут содержать правильный адрес буфера и его размер, соответственно.

Функция getdelim() работает аналогично getline(), за исключением того, что в аргументе delimiter можно задать разделитель строки, отличный от символа новой строки. Как и с getline(), символ-разделитель не добавляется, если его было в входных данных до конца файла.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении getline() и getdelim() возвращают количество считанных символов, включая символ разделителя, но не включая завершающий байт null ('\0'). Это значение может использоваться для обработки встроенных байтов null при чтении строки.

Обе функции возвращают -1 при ошибках чтения строки (включая условие достижения конца файла). При возникновении ошибки в errno сохраняется её значение.

ОШИБКИ

EINVAL
    Некорректные параметры (n или lineptr равно NULL или неправильное значение stream).

ENOMEM
    Не удалось выделить или переместить строчный буфер.

АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
Интерфейс | Атрибут | Значение
getline(), getdelim() | Безвредность в нитях | MT-Safe

СООТВЕТСТВИЕ СТАНДАРТАМ
Изначально, функции getline() и getdelim() были расширениями GNU. Позднее они были стандартизированы в POSIX.1-2008.

ПРИМЕР
    #define _GNU_SOURCE
    #include <stdio.h>
    #include <stdlib.h>
    int
    main(int argc, char *argv[])
    {
        FILE *stream;
        char *line = NULL;
        size_t len = 0;
        ssize_t nread;
        if (argc != 2) {
            fprintf(stderr, "Использование: %s <файл>\n", argv[0]);
            exit(EXIT_FAILURE);
        }
        stream = fopen(argv[1], "r");
        if (stream == NULL) {
            perror("fopen");
            exit(EXIT_FAILURE);
        }
        while ((nread = getline(&line, &len, stream)) != -1) {
            printf("Retrieved line of length %zu:\n", nread);
            fwrite(line, nread, 1, stdout);
        }
        free(line);
        fclose(stream);
        exit(EXIT_SUCCESS);
    }

СМОТРИТЕ ТАКЖЕ
read(2), fgets(3), fopen(3), fread(3), scanf(3)