]>
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. | |
c13182ef | 12 | .\" |
fea681da MK |
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. | |
c13182ef | 20 | .\" |
fea681da MK |
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. | |
2df47dc8 | 24 | .TH GETLINE 3 2006-05-17 "GNU" "Linux Programmer's Manual" |
fea681da MK |
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 ); | |
5895e7eb | 33 | |
c8250206 MK |
34 | .BI "ssize_t getdelim(char **" lineptr ", size_t *" n ", int " delim \ |
35 | ", FILE *" stream ); | |
36 | .fi | |
fea681da | 37 | .SH DESCRIPTION |
63aa9df0 | 38 | .BR getline () |
c13182ef | 39 | reads an entire line from \fIstream\fP, |
2df47dc8 | 40 | storing the address of the buffer containing the text into |
a5e0a0e4 | 41 | .IR "*lineptr" . |
2df47dc8 MK |
42 | The buffer is null-terminated and includes the newline character, if |
43 | one was found. | |
fea681da | 44 | |
fea681da | 45 | If |
0daa9e92 | 46 | .I "*lineptr" |
2df47dc8 | 47 | is NULL, then |
63aa9df0 | 48 | .BR getline () |
865be3cc MK |
49 | will allocate a buffer for storing the line, |
50 | which should be freed by the user program. | |
51 | (The value in | |
52 | .I *n | |
53 | is ignored.) | |
54 | ||
fea681da | 55 | Alternatively, before calling |
e1d6264d | 56 | .BR getline (), |
0daa9e92 | 57 | .I "*lineptr" |
fea681da | 58 | can contain a pointer to a |
fb186734 | 59 | .BR malloc (3)\-allocated |
fea681da | 60 | buffer |
0daa9e92 | 61 | .I "*n" |
c13182ef MK |
62 | bytes in size. |
63 | If the buffer is not large enough to hold the line, | |
63aa9df0 | 64 | .BR getline () |
2df47dc8 | 65 | resizes it with |
fb186734 | 66 | .BR realloc (3), |
fea681da | 67 | updating |
0daa9e92 | 68 | .I "*lineptr" |
fea681da | 69 | and |
0daa9e92 | 70 | .I "*n" |
c13182ef | 71 | as necessary. |
865be3cc | 72 | |
c13182ef | 73 | In either case, on a successful call, |
0daa9e92 | 74 | .I "*lineptr" |
fea681da | 75 | and |
0daa9e92 | 76 | .I "*n" |
2df47dc8 | 77 | will be updated to reflect the buffer address and allocated size respectively. |
fea681da | 78 | |
63aa9df0 | 79 | .BR getdelim () |
fea681da | 80 | works like |
e1d6264d | 81 | .BR getline (), |
fea681da | 82 | except a line delimiter other than newline can be specified as the |
0daa9e92 | 83 | .I delimiter |
c13182ef MK |
84 | argument. |
85 | As with | |
e1d6264d | 86 | .BR getline (), |
fea681da MK |
87 | a delimiter character is not added if one was not present |
88 | in the input before end of file was reached. | |
fea681da MK |
89 | .SH "RETURN VALUE" |
90 | On success, | |
e1d6264d | 91 | .BR getline () |
fea681da | 92 | and |
f87925c6 | 93 | .BR getdelim () |
fea681da | 94 | return the number of characters read, including the delimiter character, |
c13182ef MK |
95 | but not including the terminating null byte. |
96 | This value can be used | |
28d88c17 | 97 | to handle embedded null bytes in the line read. |
fea681da MK |
98 | |
99 | Both functions return \-1 on failure to read a line (including end of file | |
100 | condition). | |
fea681da MK |
101 | .SH ERRORS |
102 | .TP | |
103 | .B EINVAL | |
104 | Bad parameters | |
105 | .RI ( n | |
106 | or | |
107 | .I lineptr | |
108 | is NULL, or | |
109 | .I stream | |
110 | is not valid). | |
2b2581ee MK |
111 | .SH "CONFORMING TO" |
112 | Both | |
113 | .BR getline () | |
114 | and | |
115 | .BR getdelim () | |
116 | are GNU extensions. | |
117 | They are available since libc 4.6.27. | |
fea681da MK |
118 | .SH "EXAMPLE" |
119 | .nf | |
120 | #define _GNU_SOURCE | |
121 | #include <stdio.h> | |
122 | #include <stdlib.h> | |
123 | ||
c13182ef | 124 | int |
cf0a9ace | 125 | main(void) |
fea681da | 126 | { |
cf0a9ace MK |
127 | FILE * fp; |
128 | char * line = NULL; | |
129 | size_t len = 0; | |
130 | ssize_t read; | |
131 | fp = fopen("/etc/motd", "r"); | |
132 | if (fp == NULL) | |
133 | exit(EXIT_FAILURE); | |
134 | while ((read = getline(&line, &len, fp)) != \-1) { | |
135 | printf("Retrieved line of length %zu :\en", read); | |
136 | printf("%s", line); | |
137 | } | |
138 | if (line) | |
139 | free(line); | |
140 | return EXIT_SUCCESS; | |
fea681da MK |
141 | } |
142 | .fi | |
fea681da MK |
143 | .SH "SEE ALSO" |
144 | .BR read (2), | |
145 | .BR fgets (3), | |
146 | .BR fopen (3), | |
147 | .BR fread (3), | |
148 | .BR gets (3), | |
0a90178c MK |
149 | .BR scanf (3), |
150 | .BR feature_test_macros (7) |