mirror of https://github.com/mkerrisk/man-pages
142 lines
3.8 KiB
Groff
142 lines
3.8 KiB
Groff
.\" Copyright (c) 2001 John Levon <moz@compsoc.man.ac.uk>
|
|
.\" Based in part on GNU libc documentation
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" License.
|
|
.TH GETLINE 3 2006-05-17 "GNU" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
getline, getdelim \- delimited string input
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #define _GNU_SOURCE
|
|
.B #include <stdio.h>
|
|
.sp
|
|
.BI "ssize_t getline(char **" lineptr ", size_t *" n ", FILE *" stream );
|
|
.br
|
|
.BI "ssize_t getdelim(char **" lineptr ", size_t *" n ", int " delim ", FILE *" stream );
|
|
.SH DESCRIPTION
|
|
.BR getline ()
|
|
reads an entire line from \fIstream\fP,
|
|
storing the address of the buffer containing the text into
|
|
.IR "*lineptr" .
|
|
The buffer is null-terminated and includes the newline character, if
|
|
one was found.
|
|
|
|
.\" FIXME what happens if *lineptr is NULL but *n isn't zero ?
|
|
.\" Answer: *n is ignored and a new buffer is allocated
|
|
If
|
|
.IR "*lineptr"
|
|
is NULL, then
|
|
.BR getline ()
|
|
will allocate a buffer for storing the line, which should be freed
|
|
by the user program.
|
|
Alternatively, before calling
|
|
.BR getline (),
|
|
.IR "*lineptr"
|
|
can contain a pointer to a
|
|
.BR malloc ()\-allocated
|
|
buffer
|
|
.IR "*n"
|
|
bytes in size. If the buffer is not large enough to hold the line,
|
|
.BR getline ()
|
|
resizes it with
|
|
.BR realloc (),
|
|
updating
|
|
.IR "*lineptr"
|
|
and
|
|
.IR "*n"
|
|
as necessary. In either case, on a successful call,
|
|
.IR "*lineptr"
|
|
and
|
|
.IR "*n"
|
|
will be updated to reflect the buffer address and allocated size respectively.
|
|
|
|
.BR getdelim ()
|
|
works like
|
|
.BR getline (),
|
|
except a line delimiter other than newline can be specified as the
|
|
.IR delimiter
|
|
argument. As with
|
|
.BR getline (),
|
|
a delimiter character is not added if one was not present
|
|
in the input before end of file was reached.
|
|
.SH "RETURN VALUE"
|
|
On success,
|
|
.BR getline ()
|
|
and
|
|
.BR getdelim ()
|
|
return the number of characters read, including the delimiter character,
|
|
but not including the terminating null byte. This value can be used
|
|
to handle embedded null bytes in the line read.
|
|
|
|
Both functions return \-1 on failure to read a line (including end of file
|
|
condition).
|
|
.SH ERRORS
|
|
.TP
|
|
.B EINVAL
|
|
Bad parameters
|
|
.RI ( n
|
|
or
|
|
.I lineptr
|
|
is NULL, or
|
|
.I stream
|
|
is not valid).
|
|
.SH "EXAMPLE"
|
|
.nf
|
|
#define _GNU_SOURCE
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
|
|
int
|
|
main(void)
|
|
{
|
|
FILE * fp;
|
|
char * line = NULL;
|
|
size_t len = 0;
|
|
ssize_t read;
|
|
fp = fopen("/etc/motd", "r");
|
|
if (fp == NULL)
|
|
exit(EXIT_FAILURE);
|
|
while ((read = getline(&line, &len, fp)) != \-1) {
|
|
printf("Retrieved line of length %zu :\en", read);
|
|
printf("%s", line);
|
|
}
|
|
if (line)
|
|
free(line);
|
|
return EXIT_SUCCESS;
|
|
}
|
|
.fi
|
|
.SH "CONFORMING TO"
|
|
Both
|
|
.BR getline ()
|
|
and
|
|
.BR getdelim ()
|
|
are GNU extensions.
|
|
They are available since libc 4.6.27.
|
|
.SH "SEE ALSO"
|
|
.BR read (2),
|
|
.BR fgets (3),
|
|
.BR fopen (3),
|
|
.BR fread (3),
|
|
.BR gets (3),
|
|
.BR scanf (3),
|
|
.BR feature_test_macros (7)
|