1 '\" t
   2 .\"
   3 .\" This file and its contents are supplied under the terms of the
   4 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   5 .\" You may only use this file in accordance with the terms of version
   6 .\" 1.0 of the CDDL.
   7 .\"
   8 .\" A full copy of the text of the CDDL should have accompanied this
   9 .\" source.  A copy of the CDDL is also available via the Internet at
  10 .\" http://www.illumos.org/license/CDDL.
  11 .\"
  12 .\"
  13 .\" Copyright (c) 2013, Joyent, Inc. All rights reserved.
  14 .\"
  15 .TH GETLINE 3C "Apr 24, 2013"
  16 .SH NAME
  17 getline, getdelim \- read delimited input from streams
  18 .SH SYNOPSIS
  19 .LP
  20 .nf
  21 #include <stdio.h>
  22 .fi
  23 
  24 .LP
  25 .nf
  26 \fBssize_t\fR \fBgetline\fR(\fBchar **restrict\fR \fIptr\fR, \
  27 \fBsize_t *restrict\fR \fIcap\fR,
  28     \fBFILE *restrict\fR \fIstream\fR);
  29 .fi
  30 
  31 .LP
  32 .nf
  33 \fBssize_t\fR \fBgetdelim\fR(\fBchar **restrict\fR \fIptr\fR, \
  34 \fBsize_t *restrict\fR \fIcap\fR,
  35     \fBint\fR \fIdelimiter\fR, \fBFILE *restrict\fR \fIstream\fR);
  36 .fi
  37 
  38 .SH DESCRIPTION
  39 The \fBgetdelim\fR() function reads bytes from the \fIstream\fR into the the
  40 array pointed to by \fIptr\fR, until the \fIdelimiter\fR byte or an end-of-file
  41 condition is encountered.  The \fBgetline\fR() function is identical in
  42 behaviour, but uses the newline character as the delimiter.  The delimiter
  43 character is included in the string (unless end-of-file was reached first) and
  44 the string is terminated with a null byte.
  45 
  46 The caller may pass a pre-allocated \fBmalloc\fR(3C) buffer as \fI*ptr\fR,
  47 along with the capacity of that buffer as \fI*cap\fR.  It is also valid to pass
  48 \fBNULL\fR for \fI*ptr\fR and \fB0\fR for \fI*cap\fR, at which point memory
  49 will be allocated automatically.  If the buffer provided is not large enough to
  50 hold the string it will be expanded, as if via \fBrealloc(3C)\fR.  The caller
  51 must \fBfree(3C)\fR the buffer when it is no longer required.
  52 
  53 .SH RETURN VALUES
  54 .sp
  55 .LP
  56 If successful, \fBgetdelim\fR() and \fBgetline\fR() return the number of bytes
  57 written into the buffer, excluding the terminating null byte.  If an error
  58 occurs, or if end-of-file is reached prior to reading any bytes, the value
  59 \fB\(mi1\fR is returned and \fIerrno\fR is set to indicate the error.
  60 
  61 .SH ERRORS
  62 .sp
  63 .LP
  64 The \fBgetline\fR() and \fBgetdelim\fR() functions may fail due to the
  65 following errors:
  66 
  67 .sp
  68 .ne 2
  69 .na
  70 \fBEINVAL\fR
  71 .ad
  72 .RS 13n
  73 Either \fIptr\fR or \fIcap\fR are \fBNULL\fR, or the \fIdelimiter\fR is
  74 not a valid character.
  75 .RE
  76 
  77 .sp
  78 .ne 2
  79 .na
  80 \fBEOVERFLOW\fR
  81 .ad
  82 .RS 13n
  83 More than \fBSSIZE_MAX\fR characters were read from the stream without
  84 encountering the \fIdelimiter\fR.
  85 .RE
  86 
  87 .sp
  88 .LP
  89 The \fBgetline\fR() and \fBgetdelim\fR() functions may also fail and set
  90 \fIerrno\fR for any of the errors specified for the library routines
  91 \fBrealloc\fR(3C) or \fBfgetc\fR(3C).
  92 
  93 .SH EXAMPLES
  94 .LP
  95 \fBExample 1\fR Read a line from \fBstdin\fR.
  96 .sp
  97 .LP
  98 The following example uses \fBgetline\fR to read a line from stdin.
  99 
 100 .sp
 101 .in +2
 102 .nf
 103 #include <stdio.h>
 104 \&...
 105 char *ptr = NULL;
 106 size_t cap = 0;
 107 
 108 if (getline(&ptr, &cap, stdin) == -1) {
 109     perror("getline");
 110     exit(1);
 111 }
 112 fprintf(stdout, "input line: %s", ptr);
 113 
 114 free(ptr);
 115 .
 116 .fi
 117 .in -2
 118 
 119 .SH ATTRIBUTES
 120 .sp
 121 .TS
 122 box;
 123 c | c
 124 l | l .
 125 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 126 _
 127 Interface Stability     Committed
 128 _
 129 MT-Level        MT-Safe
 130 .TE
 131 
 132 .SH SEE ALSO
 133 .sp
 134 .LP
 135 \fBfgetc\fR(3C), \fBfgets\fR(3C), \fBfree\fR(3C), \fBmalloc\fR(3C),
 136 \fBrealloc\fR(3C), \fBattributes\fR(5)