167 lines
4.2 KiB
Groff
167 lines
4.2 KiB
Groff
.\" Copyright (c) 2009 David Schultz <das@FreeBSD.org>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd November 30, 2012
|
|
.Dt GETLINE 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm getdelim ,
|
|
.Nm getline
|
|
.Nd get a line from a stream
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.Fd "#define _WITH_GETLINE"
|
|
.In stdio.h
|
|
.Ft ssize_t
|
|
.Fn getdelim "char ** restrict linep" "size_t * restrict linecapp" "int delimiter" " FILE * restrict stream"
|
|
.Ft ssize_t
|
|
.Fn getline "char ** restrict linep" "size_t * restrict linecapp" " FILE * restrict stream"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn getdelim
|
|
function reads a line from
|
|
.Fa stream ,
|
|
delimited by the character
|
|
.Fa delimiter .
|
|
The
|
|
.Fn getline
|
|
function is equivalent to
|
|
.Fn getdelim
|
|
with the newline character as the delimiter.
|
|
The delimiter character is included as part of the line, unless
|
|
the end of the file is reached.
|
|
.Pp
|
|
The caller may provide a pointer to a malloced buffer for the line in
|
|
.Fa *linep ,
|
|
and the capacity of that buffer in
|
|
.Fa *linecapp .
|
|
These functions expand the buffer as needed, as if via
|
|
.Fn realloc .
|
|
If
|
|
.Fa linep
|
|
points to a
|
|
.Dv NULL
|
|
pointer, a new buffer will be allocated.
|
|
In either case,
|
|
.Fa *linep
|
|
and
|
|
.Fa *linecapp
|
|
will be updated accordingly.
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn getdelim
|
|
and
|
|
.Fn getline
|
|
functions return the number of characters stored in the buffer, excluding the
|
|
terminating
|
|
.Dv NUL
|
|
character.
|
|
The value \-1 is returned if an error occurs, or if end-of-file is reached.
|
|
.Sh EXAMPLES
|
|
The following code fragment reads lines from a file and
|
|
writes them to standard output.
|
|
The
|
|
.Fn fwrite
|
|
function is used in case the line contains embedded
|
|
.Dv NUL
|
|
characters.
|
|
.Bd -literal -offset indent
|
|
char *line = NULL;
|
|
size_t linecap = 0;
|
|
ssize_t linelen;
|
|
while ((linelen = getline(&line, &linecap, fp)) > 0)
|
|
fwrite(line, linelen, 1, stdout);
|
|
free(line);
|
|
.Ed
|
|
.Sh COMPATIBILITY
|
|
Many application writers used the name
|
|
.Va getline
|
|
before the
|
|
.Fn getline
|
|
function was introduced in
|
|
.St -p1003.1 ,
|
|
so a prototype is not provided by default in order to avoid
|
|
compatibility problems.
|
|
Applications that wish to use the
|
|
.Fn getline
|
|
function described herein should either request a strict
|
|
.St -p1003.1-2008
|
|
environment by defining the macro
|
|
.Dv _POSIX_C_SOURCE
|
|
to the value 200809 or greater, or by defining the macro
|
|
.Dv _WITH_GETLINE ,
|
|
prior to the inclusion of
|
|
.In stdio.h .
|
|
For compatibility with GNU libc, defining either
|
|
.Dv _BSD_SOURCE
|
|
or
|
|
.Dv _GNU_SOURCE
|
|
prior to the inclusion of
|
|
.In stdio.h
|
|
will also make
|
|
.Fn getline
|
|
available.
|
|
.Sh ERRORS
|
|
These functions may fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
Either
|
|
.Fa linep
|
|
or
|
|
.Fa linecapp
|
|
is
|
|
.Dv NULL .
|
|
.It Bq Er EOVERFLOW
|
|
No delimiter was found in the first
|
|
.Dv SSIZE_MAX
|
|
characters.
|
|
.El
|
|
.Pp
|
|
These functions may also fail due to any of the errors specified for
|
|
.Fn fgets
|
|
and
|
|
.Fn malloc .
|
|
.Sh SEE ALSO
|
|
.Xr fgetln 3 ,
|
|
.Xr fgets 3 ,
|
|
.Xr malloc 3
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn getdelim
|
|
and
|
|
.Fn getline
|
|
functions conform to
|
|
.St -p1003.1-2008 .
|
|
.Sh HISTORY
|
|
These routines first appeared in
|
|
.Fx 8.0 .
|
|
.Sh BUGS
|
|
There are no wide character versions of
|
|
.Fn getdelim
|
|
or
|
|
.Fn getline .
|