Print this page
Whoops!  Wrong file modified!

@@ -1,6 +1,5 @@
-'\" 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.

@@ -9,99 +8,90 @@
 .\" 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.
+.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
 .\"
-.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
+.Dd "Apr 24, 2013"
+.Dt GETLINE 3C
+.Os
+.Sh NAME
+.Nm getline ,
+.Nm getdelim
+.Nd read delimited input from streams
+.Sh SYNOPSIS
+.In stdio.h
+.Ft ssize_t
+.Fo getline
+.Fa "char **restrict ptr"
+.Fa "size_t *restrict cap"
+.Fa "FILE *restrict stream"
+.Fc
+.
+.Ft ssize_t
+.Fo getdelim
+.Fa "char **restrict ptr"
+.Fa "size_t *restrict cap"
+.Fa "int delimiter"
+.Fa "FILE *restrict stream"
+.Fc
+.
+.Sh DESCRIPTION
+The
+.Fn getdelim
+function reads bytes from the
+.Fa stream
+into the the
+array pointed to by
+.Fa ptr ,
+until the
+.Fa delimiter
+byte or an end-of-file condition is encountered. The
+.Fa getline
+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
+.Lp
+The caller may pass a buffer pre-allocated with
+.Xr malloc 3C
+as
+.Fa *ptr ,
+along with the capacity of that buffer as
+.Fa *cap .
+It is also valid to pass
+.Dv NULL
+for
+.Fa *ptr
+and 0 for
+.Fa *cap ,
+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
+hold the string it will be expanded, as if via
+.Xr realloc 3C .
+The caller should
+.Xr free 3C
+the buffer when it is no longer required.
+.Sh RETURN VALUES
+If successful,
+.Fn getdelim
+and
+.Fn getline
+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
+\(mi1 is returned and
+.Va errno
+is set to indicate the error.
+.Sh EXAMPLES
+.Ss Example 1 Read a line from Va stdin
+The following example uses
+.Fn getline
+to read a line from
+.Va stdin .
+.Bd -literal -offset indent
 #include <stdio.h>
 \&...
 char *ptr = NULL;
 size_t cap = 0;
 

@@ -110,27 +100,53 @@
     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)
+.Ed
+.Sh ERRORS
+The
+.Fn getline
+and
+.Fn getdelim
+functions may fail due to the following errors:
+.Bl -tag -width Er
+.It Er EINVAL
+Either
+.Fa ptr
+or
+.Fa cap are
+.Dv NULL , or th
+.Fa delimiter
+is not a valid character.
+.It Er EOVERFLOW
+More than
+.Dv SSIZE_MAX
+characters were read from the stream without
+encountering the
+.Fa delimiter .
+.El
+.Lp
+The
+.Fn getline
+and
+.Fn getdelim
+functions may also fail and set
+.Va errno
+for any of the errors specified for the library routines
+.Xr realloc 3C
+or
+.Xr fgetc 3C .
+.Sh INTERFACE STABILITY
+.Sy Standard .
+.Sh MT-LEVEL
+.Sy MT-Safe .
+.Sh SEE ALSO
+.Xr fgetc 3C ,
+.Xr fgets 3C ,
+.Xr free 3C ,
+.Xr malloc 3C ,
+.Xr realloc 3C ,
+.Xr standards 5
+.Sh STANDARDS
+These functions were introduced in
+.St -p1003.1-2008 .