1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright (c) 2013, Joyent, Inc. All rights reserved.
  13 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
  14 .\"
  15 .Dd "Apr 24, 2013"
  16 .Dt GETLINE 3C
  17 .Os
  18 .Sh NAME
  19 .Nm getline ,
  20 .Nm getdelim
  21 .Nd read delimited input from streams
  22 .Sh SYNOPSIS
  23 .In stdio.h
  24 .Ft ssize_t
  25 .Fo getline
  26 .Fa "char **restrict ptr"
  27 .Fa "size_t *restrict cap"
  28 .Fa "FILE *restrict stream"
  29 .Fc
  30 .
  31 .Ft ssize_t
  32 .Fo getdelim
  33 .Fa "char **restrict ptr"
  34 .Fa "size_t *restrict cap"
  35 .Fa "int delimiter"
  36 .Fa "FILE *restrict stream"
  37 .Fc
  38 .
  39 .Sh DESCRIPTION
  40 The
  41 .Fn getdelim
  42 function reads bytes from the
  43 .Fa stream
  44 into the the
  45 array pointed to by
  46 .Fa ptr ,
  47 until the
  48 .Fa delimiter
  49 byte or an end-of-file condition is encountered. The
  50 .Fa getline
  51 function is identical in
  52 behaviour, but uses the newline character as the delimiter.  The delimiter
  53 character is included in the string (unless end-of-file was reached first) and
  54 the string is terminated with a null byte.
  55 .Lp
  56 The caller may pass a buffer pre-allocated with
  57 .Xr malloc 3C
  58 as
  59 .Fa *ptr ,
  60 along with the capacity of that buffer as
  61 .Fa *cap .
  62 It is also valid to pass
  63 .Dv NULL
  64 for
  65 .Fa *ptr
  66 and 0 for
  67 .Fa *cap ,
  68 at which point memory
  69 will be allocated automatically.  If the buffer provided is not large enough to
  70 hold the string it will be expanded, as if via
  71 .Xr realloc 3C .
  72 The caller should
  73 .Xr free 3C
  74 the buffer when it is no longer required.
  75 .Sh RETURN VALUES
  76 If successful,
  77 .Fn getdelim
  78 and
  79 .Fn getline
  80 return the number of bytes
  81 written into the buffer, excluding the terminating null byte.  If an error
  82 occurs, or if end-of-file is reached prior to reading any bytes, the value
  83 \(mi1 is returned and
  84 .Va errno
  85 is set to indicate the error.
  86 .Sh EXAMPLES
  87 .Ss Example 1 Read a line from Va stdin
  88 The following example uses
  89 .Fn getline
  90 to read a line from
  91 .Va stdin .
  92 .Bd -literal -offset indent
  93 #include <stdio.h>
  94 \&...
  95 char *ptr = NULL;
  96 size_t cap = 0;
  97 
  98 if (getline(&ptr, &cap, stdin) == -1) {
  99     perror("getline");
 100     exit(1);
 101 }
 102 fprintf(stdout, "input line: %s", ptr);
 103 
 104 free(ptr);
 105 .Ed
 106 .Sh ERRORS
 107 The
 108 .Fn getline
 109 and
 110 .Fn getdelim
 111 functions may fail due to the following errors:
 112 .Bl -tag -width Er
 113 .It Er EINVAL
 114 Either
 115 .Fa ptr
 116 or
 117 .Fa cap are
 118 .Dv NULL , or th
 119 .Fa delimiter
 120 is not a valid character.
 121 .It Er EOVERFLOW
 122 More than
 123 .Dv SSIZE_MAX
 124 characters were read from the stream without
 125 encountering the
 126 .Fa delimiter .
 127 .El
 128 .Lp
 129 The
 130 .Fn getline
 131 and
 132 .Fn getdelim
 133 functions may also fail and set
 134 .Va errno
 135 for any of the errors specified for the library routines
 136 .Xr realloc 3C
 137 or
 138 .Xr fgetc 3C .
 139 .Sh INTERFACE STABILITY
 140 .Sy Standard .
 141 .Sh MT-LEVEL
 142 .Sy MT-Safe .
 143 .Sh SEE ALSO
 144 .Xr fgetc 3C ,
 145 .Xr fgets 3C ,
 146 .Xr free 3C ,
 147 .Xr malloc 3C ,
 148 .Xr realloc 3C ,
 149 .Xr standards 5
 150 .Sh STANDARDS
 151 These functions were introduced in
 152 .St -p1003.1-2008 .