3822 need getline() and getdelim() manual pages

Reviewed by: Richard Lowe <richlowe@richlowe.net>
Approved by: Robert Mustacchi <rm@joyent.com>

3 files changed, 142 insertions, 0 deletions

diff --git a/usr/src/man/man3c/Makefile b/usr/src/man/man3c/Makefile
index 7d7113db7c..ae5b8542bd 100644
--- a/usr/src/man/man3c/Makefile
+++ b/usr/src/man/man3c/Makefile
@@ -150,6 +150,7 @@ MANFILES = 	__fbufsize.3c					\
 	 	gethostid.3c					\
 	 	gethostname.3c					\
 	 	gethrtime.3c					\
+		getline.3c					\
 	 	getloadavg.3c					\
 	 	getlogin.3c					\
 	 	getmntent.3c					\
@@ -749,6 +750,7 @@ MANSOFILES =	FD_CLR.3c				\
 	 	getc_unlocked.3c			\
 	 	getchar.3c				\
 	 	getchar_unlocked.3c			\
+		getdelim.3c				\
 	 	getextmntent.3c				\
 	 	getgrent.3c				\
 	 	getgrent_r.3c				\
@@ -1511,6 +1513,8 @@ sethostname.3c				:= SOSRC = man3c/gethostname.3c
 
 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
diff --git a/usr/src/man/man3c/getline.3c b/usr/src/man/man3c/getline.3c
new file mode 100644
index 0000000000..a8db7df218
--- /dev/null
+++ b/usr/src/man/man3c/getline.3c
@@ -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)
diff --git a/usr/src/pkg/manifests/system-library.man3c.inc b/usr/src/pkg/manifests/system-library.man3c.inc
index 4f8e3aca51..116c6f331e 100644
--- a/usr/src/pkg/manifests/system-library.man3c.inc
+++ b/usr/src/pkg/manifests/system-library.man3c.inc
@@ -384,6 +384,7 @@ file path=usr/share/man/man3c/getchar_unlocked.3c
 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/gethostid.3c
 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