diff options
Diffstat (limited to 'man-pages-posix-2013/man3p/getdelim.3p')
| -rw-r--r-- | man-pages-posix-2013/man3p/getdelim.3p | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/man-pages-posix-2013/man3p/getdelim.3p b/man-pages-posix-2013/man3p/getdelim.3p new file mode 100644 index 0000000..92e8255 --- /dev/null +++ b/man-pages-posix-2013/man3p/getdelim.3p @@ -0,0 +1,221 @@ +'\" et +.TH GETDELIM "3P" 2013 "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 +The size of the object pointed to by +.IR *lineptr +shall be increased to fit the incoming line, if it isn't already large +enough, including room for the delimiter and a terminating NUL. The +characters read, including any delimiter, shall be stored in the string +pointed to by the +.IR lineptr +argument, 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 characters written into the buffer, +including the delimiter character if one was encountered before EOF, +but excluding the terminating NUL character. If no characters were read, +and the end-of-file indicator for the stream is set, or if the stream is +at end-of-file, the end-of-file indicator for the stream shall be set and +the function shall return \(mi1. If an error occurs, the error indicator +for the stream shall be set, and the function shall return \(mi1 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. +.P +These functions may fail if: +.TP +.BR EOVERFLOW +More than +{SSIZE_MAX} +characters were read without encountering the +.IR delimiter +character. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.sp +.RS 4 +.nf +\fB +#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 \fR +.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\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "\fB<stdio.h>\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html . + +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 . |