diff options
Diffstat (limited to 'lib/libc/stdio/getline.3')
-rw-r--r-- | lib/libc/stdio/getline.3 | 165 |
1 files changed, 165 insertions, 0 deletions
diff --git a/lib/libc/stdio/getline.3 b/lib/libc/stdio/getline.3 new file mode 100644 index 0000000..e0dda08 --- /dev/null +++ b/lib/libc/stdio/getline.3 @@ -0,0 +1,165 @@ +.\" 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, 2010 +.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 written, 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); +.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 . |