diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/getdelim.3p')
| -rw-r--r-- | man-pages-posix-2017/man3p/getdelim.3p | 235 |
1 files changed, 235 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/getdelim.3p b/man-pages-posix-2017/man3p/getdelim.3p new file mode 100644 index 0000000..3640994 --- /dev/null +++ b/man-pages-posix-2017/man3p/getdelim.3p @@ -0,0 +1,235 @@ +'\" et +.TH GETDELIM "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 +getdelim, getline +\(em read a delimited record from +.IR stream +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +.P +ssize_t getdelim(char **restrict \fIlineptr\fP, size_t *restrict \fIn\fP, + int \fIdelimiter\fP, FILE *restrict \fIstream\fP); +ssize_t getline(char **restrict \fIlineptr\fP, size_t *restrict \fIn\fP, + FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The +\fIgetdelim\fR() +function shall read from +.IR stream +until it encounters a character matching the +.IR delimiter +character. The +.IR delimiter +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +of equal value that terminates the read process. If the +.IR delimiter +argument has any other value, the behavior is undefined. +.P +The application shall ensure that +.IR *lineptr +is a valid argument that could be passed to the +\fIfree\fR() +function. If +.IR *n +is non-zero, the application shall ensure that +.IR *lineptr +either points to an object of size at least +.IR *n +bytes, or is a null pointer. +.P +If +.IR *lineptr +is a null pointer or if the object pointed to by +.IR *lineptr +is of insufficient size, an object shall be allocated as if by +\fImalloc\fR() +or the object shall be reallocated as if by +\fIrealloc\fR(), +respectively, such that the object is large enough to hold +the characters to be written to it, including the terminating NUL, +and +.IR *n +shall be set to the new size. If the object was allocated, +or if the reallocation operation moved the object, +.IR *lineptr +shall be updated to point to the new object or new location. +The characters read, including any delimiter, shall be stored +in the object, and a terminating NUL added when the delimiter +or end-of-file is encountered. +.P +The +\fIgetline\fR() +function shall be equivalent to the +\fIgetdelim\fR() +function with the +.IR delimiter +character equal to the +<newline> +character. +.P +The +\fIgetdelim\fR() +and +\fIgetline\fR() +functions 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, the +\fIgetline\fR() +and +\fIgetdelim\fR() +functions shall return the number of bytes written into the buffer, +including the delimiter character if one was encountered before EOF, +but excluding the terminating NUL character. If the end-of-file +indicator for the stream is set, or if no characters were read and the +stream is at end-of-file, the end-of-file indicator for the +stream shall be set and the function shall return \-1. +If an error occurs, the error indicator for the stream shall be set, +and the function shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +For the conditions under which the +\fIgetdelim\fR() +and +\fIgetline\fR() +functions shall fail and may fail, refer to +.IR "\fIfgetc\fR\^(\|)". +.P +In addition, these functions shall fail if: +.TP +.BR EINVAL +.IR lineptr +or +.IR n +is a null pointer. +.TP +.BR ENOMEM +Insufficient memory is available. +.br +.P +These functions may fail if: +.TP +.BR EOVERFLOW +The number of bytes to be written into the buffer, including the +delimiter character (if encountered), would exceed +{SSIZE_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.sp +.RS 4 +.nf + +#include <stdio.h> +#include <stdlib.h> +.P +int main(void) +{ + FILE *fp; + char *line = NULL; + size_t len = 0; + ssize_t read; + fp = fopen("/etc/motd", "r"); + if (fp == NULL) + exit(1); + while ((read = getline(&line, &len, fp)) != -1) { + printf("Retrieved line of length %zu :\en", read); + printf("%s", line); + } + if (ferror(fp)) { + /* handle error */ + } + free(line); + fclose(fp); + return 0; +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +Setting +.IR *lineptr +to a null pointer and +.IR *n +to zero are allowed and a recommended way to start parsing a file. +.P +The +\fIferror\fR() +or +\fIfeof\fR() +functions should be used to distinguish between an error condition and +an end-of-file condition. +.P +Although a NUL terminator is always supplied after the line, note that +.IR strlen (* lineptr ) +will be smaller than the return value if the line contains embedded +NUL characters. +.SH RATIONALE +These functions are widely used to solve the problem that the +\fIfgets\fR() +function has with long lines. The functions automatically enlarge the +target buffers if needed. These are especially useful since they reduce +code needed for applications. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfgetc\fR\^(\|)", +.IR "\fIfgets\fR\^(\|)", +.IR "\fIfree\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fIrealloc\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 . |