]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 2001 John Levon <moz@compsoc.man.ac.uk> |
2 | .\" Based in part on GNU libc documentation | |
3 | .\" | |
4 | .\" Permission is granted to make and distribute verbatim copies of this | |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
12 | .\" | |
13 | .\" Since the Linux kernel and libraries are constantly changing, this | |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
20 | .\" | |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
23 | .\" License. | |
24 | .TH GETLINE 3 2001-10-07 "GNU" "Linux Programmer's Manual" | |
25 | .SH NAME | |
26 | getline, getdelim \- delimited string input | |
27 | .SH SYNOPSIS | |
28 | .nf | |
29 | .B #define _GNU_SOURCE | |
30 | .B #include <stdio.h> | |
31 | .sp | |
32 | .BI "ssize_t getline(char **" lineptr ", size_t *" n ", FILE *" stream ); | |
33 | .nl | |
34 | .BI "ssize_t getdelim(char **" lineptr ", size_t *" n ", int " delim ", FILE *" stream ); | |
35 | .SH DESCRIPTION | |
63aa9df0 | 36 | .BR getline () |
fea681da MK |
37 | reads an entire line, storing the address of the buffer containing |
38 | the text into | |
a5e0a0e4 | 39 | .IR "*lineptr" . |
fea681da MK |
40 | The buffer is null-terminated and includes the newline character, if a |
41 | newline delimiter was found. | |
42 | ||
43 | .\" FIXME: what happens if *lineptr is NULL but *n isn't zero ? | |
44 | .\" Answer: *n is ignored and a new buffer is allocated | |
45 | If | |
46 | .IR "*lineptr" | |
8478ee02 | 47 | is NULL, then the |
63aa9df0 | 48 | .BR getline () |
fea681da MK |
49 | routine will allocate a buffer for containing the line, which must be freed |
50 | by the user program. | |
51 | Alternatively, before calling | |
e1d6264d | 52 | .BR getline (), |
fea681da MK |
53 | .IR "*lineptr" |
54 | can contain a pointer to a | |
e1d6264d | 55 | .BR malloc ()\-allocated |
fea681da MK |
56 | buffer |
57 | .IR "*n" | |
58 | bytes in size. If the buffer is not large enough to hold the line read in, | |
63aa9df0 | 59 | .BR getline () |
fea681da | 60 | resizes the buffer to fit with |
e1d6264d | 61 | .BR realloc (), |
fea681da MK |
62 | updating |
63 | .IR "*lineptr" | |
64 | and | |
65 | .IR "*n" | |
66 | as necessary. In either case, on a successful call, | |
67 | .IR "*lineptr" | |
68 | and | |
69 | .IR "*n" | |
70 | will be updated to reflect the buffer address and size respectively. | |
71 | ||
63aa9df0 | 72 | .BR getdelim () |
fea681da | 73 | works like |
e1d6264d | 74 | .BR getline (), |
fea681da MK |
75 | except a line delimiter other than newline can be specified as the |
76 | .IR delimiter | |
77 | argument. As with | |
e1d6264d | 78 | .BR getline (), |
fea681da MK |
79 | a delimiter character is not added if one was not present |
80 | in the input before end of file was reached. | |
81 | ||
82 | .SH "RETURN VALUE" | |
83 | On success, | |
e1d6264d | 84 | .BR getline () |
fea681da | 85 | and |
f87925c6 | 86 | .BR getdelim () |
fea681da MK |
87 | return the number of characters read, including the delimiter character, |
88 | but not including the terminating null character. This value can be used | |
89 | to handle embedded null characters in the line read. | |
90 | ||
91 | Both functions return \-1 on failure to read a line (including end of file | |
92 | condition). | |
93 | ||
94 | .SH ERRORS | |
95 | .TP | |
96 | .B EINVAL | |
97 | Bad parameters | |
98 | .RI ( n | |
99 | or | |
100 | .I lineptr | |
101 | is NULL, or | |
102 | .I stream | |
103 | is not valid). | |
104 | ||
105 | .SH "EXAMPLE" | |
106 | .nf | |
107 | #define _GNU_SOURCE | |
108 | #include <stdio.h> | |
109 | #include <stdlib.h> | |
110 | ||
111 | int main(void) | |
112 | { | |
113 | FILE * fp; | |
114 | char * line = NULL; | |
115 | size_t len = 0; | |
116 | ssize_t read; | |
117 | fp = fopen("/etc/motd", "r"); | |
118 | if (fp == NULL) | |
119 | exit(EXIT_FAILURE); | |
2bc2f479 | 120 | while ((read = getline(&line, &len, fp)) != \-1) { |
fea681da MK |
121 | printf("Retrieved line of length %zu :\en", read); |
122 | printf("%s", line); | |
123 | } | |
124 | if (line) | |
125 | free(line); | |
126 | return EXIT_SUCCESS; | |
127 | } | |
128 | .fi | |
129 | .SH "CONFORMING TO" | |
b5cc2ffb MK |
130 | Both |
131 | .BR getline () | |
132 | and | |
133 | .BR getdelim () | |
134 | are GNU extensions. | |
fea681da MK |
135 | They are available since libc 4.6.27. |
136 | ||
137 | .SH "SEE ALSO" | |
138 | .BR read (2), | |
139 | .BR fgets (3), | |
140 | .BR fopen (3), | |
141 | .BR fread (3), | |
142 | .BR gets (3), | |
143 | .BR scanf (3) |