diff options
Diffstat (limited to 'upstream/archlinux/man3p/fgets.3p')
| -rw-r--r-- | upstream/archlinux/man3p/fgets.3p | 182 |
1 files changed, 182 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/fgets.3p b/upstream/archlinux/man3p/fgets.3p new file mode 100644 index 00000000..cfab9ed0 --- /dev/null +++ b/upstream/archlinux/man3p/fgets.3p @@ -0,0 +1,182 @@ +'\" et +.TH FGETS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fgets +\(em get a string from a stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +.P +char *fgets(char *restrict \fIs\fP, int \fIn\fP, FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfgets\fR() +function shall read bytes from +.IR stream +into the array pointed to by +.IR s +until +.IR n \-1 +bytes are read, or a +<newline> +is read and transferred to +.IR s , +or an end-of-file condition is encountered. A null byte shall be +written immediately after the last byte read into the array. +If the end-of-file condition is encountered before any bytes +are read, the contents of the array pointed to by +.IR s +shall not be changed. +.P +The +\fIfgets\fR() +function may mark the last data access timestamp of the file associated +with +.IR stream +for update. The last data access timestamp shall be marked for update +by the first successful execution of +\fIfgetc\fR(), +\fIfgets\fR(), +\fIfread\fR(), +\fIfscanf\fR(), +\fIgetc\fR(), +\fIgetchar\fR(), +\fIgetdelim\fR(), +\fIgetline\fR(), +\fIgets\fR(), +or +\fIscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetc\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfgets\fR() +shall return +.IR s . +If the stream is at end-of-file, the end-of-file indicator for +the stream shall be set and +\fIfgets\fR() +shall return a null pointer. +If a read error occurs, the error indicator for the stream shall be set, +\fIfgets\fR() +shall return a null pointer, +and shall set +.IR errno +to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfgetc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Reading Input" +.P +The following example uses +\fIfgets\fR() +to read lines of input. It assumes that the file it is reading is a text +file and that lines in this text file are no longer than 16384 (or +{LINE_MAX} +if it is less than 16384 on the implementation where it is running) +bytes long. (Note that the standard utilities have no line length limit if +.IR sysconf (_SC_LINE_MAX) +returns \-1 without setting +.IR errno . +This example assumes that +.IR sysconf (_SC_LINE_MAX) +will not fail.) +.sp +.RS 4 +.nf + +#include <limits.h> +#include <stdio.h> +#include <unistd.h> +#define MYLIMIT 16384 +.P +char *line; +int line_max; +if (LINE_MAX >= MYLIMIT) { + // Use maximum line size of MYLIMIT. If LINE_MAX is + // bigger than our limit, sysconf() cannot report a + // smaller limit. + line_max = MYLIMIT; +} else { + long limit = sysconf(_SC_LINE_MAX); + line_max = (limit < 0 || limit > MYLIMIT) ? MYLIMIT : (int)limit; +} +.P +// line_max + 1 leaves room for the null byte added by fgets(). +line = malloc(line_max + 1); +if (line == NULL) { + // out of space + ... + return error; +} +.P +while (fgets(line, line_max + 1, fp) != NULL) { + // Verify that a full line has been read ... + // If not, report an error or prepare to treat the + // next time through the loop as a read of a + // continuation of the current line. + ... + // Process line ... + ... +} +free(line); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfgetc\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfread\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgetchar\fR\^(\|)", +.IR "\fIgetdelim\fR\^(\|)", +.IR "\fIgets\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<stdio.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |