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
Po pomyślnym zakończeniu, getline() i getdelim() zwracają liczbę odczytanych znaków, łącznie ze znakiem ogranicznika, ale nie włączając kończącego bajtu null ('\0'). Wartość ta może służyć to wychwycenia znaków null zawartych w odczytanym wierszu.

Przy końcu pliku, obie funkcje zwracają -1 z ustawionym znacznikiem strumienia pliku: koniec pliku. W razie niepowodzenia, obie funkcje zwracają -1 z ustawionym znacznikiem strumienia pliku: błąd oraz 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 size = 0;
        ssize_t nread;

        if (argc != 2) {
            fprintf(stderr, "Użycie: %s <plik>\n", argv[0]);
            exit(EXIT_FAILURE);
        }

        stream = fopen(argv[1], "r");
        if (stream == NULL) {
            perror("fopen");
            exit(EXIT_FAILURE);
        }

        while ((nread = getline(&line, &size, stream)) != -1) {
            printf("Pobrano wiersz o długości %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
Tłumaczenie niniejszej strony podręcznika: 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.