getline(3)

NAZWA
getline, getdelim - wprowadza łańcuchy rozgraniczone

BIBLIOTEKA
Standardowa biblioteka C (libc, -lc)

SKŁADNIA
#include <stdio.h>

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

    Wymagane ustawienia makr biblioteki glibc (patrz feature_test_macros(7)):

getline(), getdelim():
    Od glibc 2.10:
        _POSIX_C_SOURCE >= 200809L
    Przed glibc 2.10:
        _GNU_SOURCE

OPIS
getline() odczytuje cały wiersz ze strumienia stream, przechowując adres bufora zawierającego tekst w *lineptr. Bufor jest zakończony znakiem NULL i zawiera znak nowego wiersza, jeśli go napotkano.

Gdy *lineptr jest ustawione na NULL przed wywołaniem, to funkcja getline() przydziela bufor dla umieszczenia w nim zawartości wiersza. Bufor ten powinien zostać zwolniony przez program użytkownika nawet wówczas, gdy getline() zawiedzie.

Alternatywnie, przed wywołaniem getline() *lineptr może zawierać wskaźnik do bufora przydzielonego za pomocą malloc() o rozmiarze *n bajtów. Gdy rozmiar bufora nie jest wystarczający do umieszczenia w nim odczytanego wiersza, getline() rozszerzy go do odpowiedniego rozmiaru za pomocą realloc(), modyfikując *lineptr i *n, jeśli będzie to potrzebne.

W każdym razie, po pomyślnym wywołaniu *lineptr i *n będą zaktualizowane tak, aby odzwierciedlić, odpowiednio, adres i rozmiar bufora.

getdelim() działa jak getline() z tym wyjątkiem, że jako argument delimiter można podać ogranicznik wiersza inny niż znak nowej wiersza. Podobnie jak dla getline(), znak ogranicznika nie jest dodawany, gdy nie występował w danych wejściowych przed osiągnięciem końca pliku.

WARTOŚĆ ZWRACANA
On success, getline() and getdelim() return the number of characters read, including the delimiter character, but not including the terminating null byte ('\0'). This value can be used to handle embedded null bytes in the line read.

Obie funkcje zwracają -1, gdy nie uda się odczytać wiersza (włączając w to próbę czytania na końcu pliku). W razie niepowodzenia ustawiane jest errno, aby wskazać błąd.

Gdy *lineptr było ustawione na NULL przed wywołaniem, to bufor powinien zostać zwolniony przez program użytkownika nawet w przypadku niepowodzenia.

BŁĘDY

EINVAL
    Błędne wartości parametrów (n lub lineptr równe NULL lub nieprawidłowy stream).

ENOMEM
    Nie powiódł się przydział pamięci dla bufora wiersza.

ATRYBUTY
Informacje o pojęciach używanych w tym rozdziale można znaleźć w podręczniku attributes(7).
Interfejs | Atrybut | Wartość
getline(), getdelim() | Bezpieczeństwo wątkowe | MT-bezpieczne

STANDARDY
POSIX.1-2008.

HISTORIA
GNU, POSIX.1-2008.

PRZYKŁADY
    #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, "Usage: %s <file>\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 %zd:\n", nread);
            fwrite(line, nread, 1, stdout);
        }

        free(line);
        fclose(stream);
        exit(EXIT_SUCCESS);
    }

ZOBACZ TAKŻE
read(2), fgets(3), fopen(3), fread(3), scanf(3)

TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl>, Robert Luberda <robert@debian.org> i Michał Kułach <michal.kulach@gmail.com>

Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać zapoznając się z GNU General Public License w wersji 3 (https://www.gnu.org/licenses/gpl-3.0.html) lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.

Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej manpages-pl-list@lists.sourceforge.net.