d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
74772ef1ae
freebsd-skq/lib/libc/stdio/getline.3

138 lines
3.6 KiB
Groff
Raw Normal View History

- 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@
2009-02-28 06:00:58 +00:00
.\" 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$
.\"
Remove _WITH_GETLINE and _WITH_DPRINTF guards When adding getline(3) and dprintf(3) into libc, those guards were added to prevent breaking too many ports. 7 years later the ports tree have been fixed, it is time to remove this FreeBSDism While here remove the extra parenthesis surrounding dprintf(3)
2016-07-30 01:00:16 +00:00
.Dd July 30, 2016
- 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@
2009-02-28 06:00:58 +00:00
.Dt GETLINE 3
.Os
.Sh NAME
.Nm getdelim ,
.Nm getline
.Nd get a line from a stream
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.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.
Update the documentation to reflect changes to the implementation in r197752, which is related to handling of null buffer pointers. Also make a few minor wording changes. Reported by: jh@
2010-11-30 21:26:21 +00:00
.Pp
The caller may provide a pointer to a malloced buffer for the line in
- 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@
2009-02-28 06:00:58 +00:00
.Fa *linep ,
and the capacity of that buffer in
Update the documentation to reflect changes to the implementation in r197752, which is related to handling of null buffer pointers. Also make a few minor wording changes. Reported by: jh@
2010-11-30 21:26:21 +00:00
.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,
- 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@
2009-02-28 06:00:58 +00:00
.Fa *linep
and
.Fa *linecapp
Update the documentation to reflect changes to the implementation in r197752, which is related to handling of null buffer pointers. Also make a few minor wording changes. Reported by: jh@
2010-11-30 21:26:21 +00:00
will be updated accordingly.
- 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@
2009-02-28 06:00:58 +00:00
.Sh RETURN VALUES
The
.Fn getdelim
and
.Fn getline
The getline function returns the number of characters read, not written. Use clearer text for this. PR: docs/174023 Submitted by: Paul Procacci <pprocacci@gmail.com> Approved by: bcr (mentor) MFC after: 1 week
2012-12-01 15:25:41 +00:00
functions return the number of characters stored in the buffer, excluding the
- 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@
2009-02-28 06:00:58 +00:00
terminating
Remove trailing whitespace per mdoc lint warning Disussed with: gavin No objection from: doc Approved by: joel MFC after: 3 days
2012-03-29 05:02:12 +00:00
.Dv NUL
2009-12-16 04:19:23 +00:00
character.
Return -1 instead of 0 upon reaching EOF. This is somewhat ill-advised because it means getdelim() returns -1 for both error and EOF, and never returns 0. However, this is what the original GNU implementation does, and POSIX inherited the bug. Reported by: marcus@
2009-04-06 13:50:04 +00:00
The value \-1 is returned if an error occurs, or if end-of-file is reached.
- 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@
2009-02-28 06:00:58 +00:00
.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);
Fix the example: free the memory that was allocated by getline().
2014-07-31 08:28:42 +00:00
free(line);
- 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@
2009-02-28 06:00:58 +00:00
.Ed
.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
Update the documentation to reflect changes to the implementation in r197752, which is related to handling of null buffer pointers. Also make a few minor wording changes. Reported by: jh@
2010-11-30 21:26:21 +00:00
These functions may also fail due to any of the errors specified for
- 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@
2009-02-28 06:00:58 +00:00
.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 .
Reference in New Issue Copy Permalink