getline(3) man手册翻译

GETLINE(3)

名字

getline, getdelim - delimited string input

概要

#include <stdio.h>

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

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

Feature Test Macro Requirements for glibc (see feature_test_macros(7))

getline(), getdelim():

Since glibc 2.10:

    _POSIX_C_SOURCE >= 200809L

Before glibc 2.10:

    _GNU_SOURCE

描述

getline()从stream里面读取完整的一行，将包含文本的缓冲的地址存储在*lineptr中。这个buffer是以‘\0’(null-terminator or null character)结尾的，如果有newline的话就包含newline。

如果在调用之前，*lineptr设置为NULL，*n设置为0，那么getline()会分配一个用于存储行的buffer。即使getline()失败了，用户也需要释放这个缓存。

作为另一种选择，在调用getline()之前，*lineptr可以包含一个指向malloc分配的*n字节缓存的buffer。如果这个buffer大小不够，那么getline会用realloc(3)来重新调整buffer的大小，并且按需更新*lineptr和*n的大小。

无论哪一种情况，在一种成功的调用之下，*lineptr和*n会跟新到反应buffer的地址和大小。

getdelim()和getline()类似，但是它可以通过delimiter参数指定line分界符，而不是像getline()只能使用newline作为line分界符。和getline一样，如果在读到EOF之前没有读到line分界符，那么buffer里面就不存储这个line分解符。

返回值

如果成功，getline()和getdelim()返回读取的字符长度（包含最后的行分界符，但是不包括null-terminator）。

两个函数都return -1来表示读行失败。如果出现错误，errno就设置来反映原因。

ERRORS

EINVAL 输入参数不对（n或者lineptr是NULL，或者stream无效）。

ENOMEM 分配或者重新分配buffer失败。

属性

要看在这个部分使用的术语的解释，请看attribute(7)。

Interface	Attribute	Value
getline(), getdelim()	Thread safety	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, "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 %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)

版权页标记

这一页是4.15 Linux man-pages项目的一部分。项目的描述、报bug相关信息以及本页的最新版本，可以在https://www.kernel.org/doc/man-pages/找到。

GNU 2017-09-15 GETLINE(3)