diff options
author | das <das@FreeBSD.org> | 2009-02-28 06:00:58 +0000 |
---|---|---|
committer | das <das@FreeBSD.org> | 2009-02-28 06:00:58 +0000 |
commit | a67fbaa46cbdf18a03eefb3f83e2f74f68918753 (patch) | |
tree | f258384b92d5c4bde23e95d4c44fa3547a0364cd /lib/libc/stdio/getline.3 | |
parent | b739b3fb48f28ef6b6e7efeeceb832d3dec3fc9c (diff) | |
download | FreeBSD-src-a67fbaa46cbdf18a03eefb3f83e2f74f68918753.zip FreeBSD-src-a67fbaa46cbdf18a03eefb3f83e2f74f68918753.tar.gz |
- Add getdelim(), getline(), stpncpy(), strnlen(), wcsnlen(),
wcscasecmp(), and wcsncasecmp().
- Make some previously non-standard extensions visible
if POSIX_VISIBLE >= 200809.
- Use restrict qualifiers in stpcpy().
- Declare off_t and size_t in stdio.h.
- Bump __FreeBSD_version in case the new symbols (particularly
getline()) cause issues with ports.
Reviewed by: standards@
Diffstat (limited to 'lib/libc/stdio/getline.3')
-rw-r--r-- | lib/libc/stdio/getline.3 | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/lib/libc/stdio/getline.3 b/lib/libc/stdio/getline.3 new file mode 100644 index 0000000..096331a --- /dev/null +++ b/lib/libc/stdio/getline.3 @@ -0,0 +1,164 @@ +.\" 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 February 28, 2009 +.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. +The caller may provide a pointer to a malloc buffer for the line in +.Fa *linep , +and the capacity of that buffer in +.Fa *linecapp ; +if +.Fa *linecapp +is 0, then +.Fa *linep +is treated as +.Dv NULL . +These functions may expand the buffer as needed, as if via +.Fn realloc , +and update +.Fa *linep +and +.Fa *linecapp +accordingly. +.Sh RETURN VALUES +The +.Fn getdelim +and +.Fn getline +functions return the number of characters written, excluding the +terminating +.Dv NUL . +The value \-1 is returned if an error occurs. +.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 for 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 . |