Mercurial > illumos > illumos-gate
changeset 14059:1a63e2c4c1b9
3822 need getline() and getdelim() manual pages
Reviewed by: Richard Lowe <richlowe@richlowe.net>
Approved by: Robert Mustacchi <rm@joyent.com>
author | Joshua M. Clulow <jmc@joyent.com> |
---|---|
date | Wed, 24 Apr 2013 18:37:28 +0000 |
parents | e9339ccf0537 |
children | aeb4e8fef072 |
files | usr/src/man/man3c/Makefile usr/src/man/man3c/getline.3c usr/src/pkg/manifests/system-library.man3c.inc |
diffstat | 3 files changed, 142 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/usr/src/man/man3c/Makefile Wed Jun 19 13:34:25 2013 -0400 +++ b/usr/src/man/man3c/Makefile Wed Apr 24 18:37:28 2013 +0000 @@ -150,6 +150,7 @@ gethostid.3c \ gethostname.3c \ gethrtime.3c \ + getline.3c \ getloadavg.3c \ getlogin.3c \ getmntent.3c \ @@ -749,6 +750,7 @@ getc_unlocked.3c \ getchar.3c \ getchar_unlocked.3c \ + getdelim.3c \ getextmntent.3c \ getgrent.3c \ getgrent_r.3c \ @@ -1511,6 +1513,8 @@ gethrvtime.3c := SOSRC = man3c/gethrtime.3c +getdelim.3c := SOSRC = man3c/getline.3c + getlogin_r.3c := SOSRC = man3c/getlogin.3c getextmntent.3c := SOSRC = man3c/getmntent.3c
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/usr/src/man/man3c/getline.3c Wed Apr 24 18:37:28 2013 +0000 @@ -0,0 +1,136 @@ +'\" t +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.\" +.\" Copyright (c) 2013, Joyent, Inc. All rights reserved. +.\" +.TH GETLINE 3C "Apr 24, 2013" +.SH NAME +getline, getdelim \- read delimited input from streams +.SH SYNOPSIS +.LP +.nf +#include <stdio.h> +.fi + +.LP +.nf +\fBssize_t\fR \fBgetline\fR(\fBchar **restrict\fR \fIptr\fR, \ +\fBsize_t *restrict\fR \fIcap\fR, + \fBFILE *restrict\fR \fIstream\fR); +.fi + +.LP +.nf +\fBssize_t\fR \fBgetdelim\fR(\fBchar **restrict\fR \fIptr\fR, \ +\fBsize_t *restrict\fR \fIcap\fR, + \fBint\fR \fIdelimiter\fR, \fBFILE *restrict\fR \fIstream\fR); +.fi + +.SH DESCRIPTION +The \fBgetdelim\fR() function reads bytes from the \fIstream\fR into the the +array pointed to by \fIptr\fR, until the \fIdelimiter\fR byte or an end-of-file +condition is encountered. The \fBgetline\fR() function is identical in +behaviour, but uses the newline character as the delimiter. The delimiter +character is included in the string (unless end-of-file was reached first) and +the string is terminated with a null byte. + +The caller may pass a pre-allocated \fBmalloc\fR(3C) buffer as \fI*ptr\fR, +along with the capacity of that buffer as \fI*cap\fR. It is also valid to pass +\fBNULL\fR for \fI*ptr\fR and \fB0\fR for \fI*cap\fR, at which point memory +will be allocated automatically. If the buffer provided is not large enough to +hold the string it will be expanded, as if via \fBrealloc(3C)\fR. The caller +must \fBfree(3C)\fR the buffer when it is no longer required. + +.SH RETURN VALUES +.sp +.LP +If successful, \fBgetdelim\fR() and \fBgetline\fR() return the number of bytes +written into the buffer, excluding the terminating null byte. If an error +occurs, or if end-of-file is reached prior to reading any bytes, the value +\fB\(mi1\fR is returned and \fIerrno\fR is set to indicate the error. + +.SH ERRORS +.sp +.LP +The \fBgetline\fR() and \fBgetdelim\fR() functions may fail due to the +following errors: + +.sp +.ne 2 +.na +\fBEINVAL\fR +.ad +.RS 13n +Either \fIptr\fR or \fIcap\fR are \fBNULL\fR, or the \fIdelimiter\fR is +not a valid character. +.RE + +.sp +.ne 2 +.na +\fBEOVERFLOW\fR +.ad +.RS 13n +More than \fBSSIZE_MAX\fR characters were read from the stream without +encountering the \fIdelimiter\fR. +.RE + +.sp +.LP +The \fBgetline\fR() and \fBgetdelim\fR() functions may also fail and set +\fIerrno\fR for any of the errors specified for the library routines +\fBrealloc\fR(3C) or \fBfgetc\fR(3C). + +.SH EXAMPLES +.LP +\fBExample 1\fR Read a line from \fBstdin\fR. +.sp +.LP +The following example uses \fBgetline\fR to read a line from stdin. + +.sp +.in +2 +.nf +#include <stdio.h> +\&... +char *ptr = NULL; +size_t cap = 0; + +if (getline(&ptr, &cap, stdin) == -1) { + perror("getline"); + exit(1); +} +fprintf(stdout, "input line: %s", ptr); + +free(ptr); +. +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.TS +box; +c | c +l | l . +ATTRIBUTE TYPE ATTRIBUTE VALUE +_ +Interface Stability Committed +_ +MT-Level MT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfgetc\fR(3C), \fBfgets\fR(3C), \fBfree\fR(3C), \fBmalloc\fR(3C), +\fBrealloc\fR(3C), \fBattributes\fR(5)
--- a/usr/src/pkg/manifests/system-library.man3c.inc Wed Jun 19 13:34:25 2013 -0400 +++ b/usr/src/pkg/manifests/system-library.man3c.inc Wed Apr 24 18:37:28 2013 +0000 @@ -384,6 +384,7 @@ file path=usr/share/man/man3c/getcpuid.3c file path=usr/share/man/man3c/getcwd.3c file path=usr/share/man/man3c/getdate.3c +file path=usr/share/man/man3c/getdelim.3c file path=usr/share/man/man3c/getdtablesize.3c file path=usr/share/man/man3c/getenv.3c file path=usr/share/man/man3c/getexecname.3c @@ -399,6 +400,7 @@ file path=usr/share/man/man3c/gethostname.3c file path=usr/share/man/man3c/gethrtime.3c file path=usr/share/man/man3c/gethrvtime.3c +file path=usr/share/man/man3c/getline.3c file path=usr/share/man/man3c/getloadavg.3c file path=usr/share/man/man3c/getlogin.3c file path=usr/share/man/man3c/getlogin_r.3c