usr/src/man/man3c/getline.3c

   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 "April 9, 2016"
  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
  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 .LP
  55 If successful, \fBgetdelim\fR() and \fBgetline\fR() return the number of bytes
  56 written into the buffer, excluding the terminating null byte.  If an error
  57 occurs, or if end-of-file is reached prior to reading any bytes, the value
  58 \fB\(mi1\fR is returned and \fIerrno\fR is set to indicate the error.
  59
  60 .SH ERRORS
  61 .LP
  62 The \fBgetline\fR() and \fBgetdelim\fR() functions may fail due to the
  63 following errors:
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fBEINVAL\fR
  69 .ad
  70 .RS 13n
  71 Either \fIptr\fR or \fIcap\fR are \fBNULL\fR, or the \fIdelimiter\fR is
  72 not a valid character.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fBEOVERFLOW\fR
  79 .ad
  80 .RS 13n
  81 More than \fBSSIZE_MAX\fR characters were read from the stream without
  82 encountering the \fIdelimiter\fR.
  83 .RE
  84
  85 .sp
  86 .LP
  87 The \fBgetline\fR() and \fBgetdelim\fR() functions may also fail and set
  88 \fIerrno\fR for any of the errors specified for the library routines
  89 \fBrealloc\fR(3C) or \fBfgetc\fR(3C).
  90
  91 .SH EXAMPLES
  92 .LP
  93 \fBExample 1\fR Read a line from \fBstdin\fR.
  94 .sp
  95 .LP
  96 The following example uses \fBgetline\fR to read a line from stdin.
  97
  98 .sp
  99 .in +2
 100 .nf
 101 #include <stdio.h>
 102 \&...
 103 char *ptr = NULL;
 104 size_t cap = 0;
 105
 106 if (getline(&ptr, &cap, stdin) == -1) {
 107     perror("getline");
 108     exit(1);
 109 }
 110 fprintf(stdout, "input line: %s", ptr);
 111
 112 free(ptr);
 113 .
 114 .fi
 115 .in -2
 116
 117 .SH ATTRIBUTES
 118 .TS
 119 box;
 120 c | c
 121 l | l .
 122 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 123 _
 124 Interface Stability     Committed
 125 _
 126 MT-Level        MT-Safe
 127 .TE
 128
 129 .SH SEE ALSO
 130 .LP
 131 \fBfgetc\fR(3C), \fBfgets\fR(3C), \fBfree\fR(3C), \fBmalloc\fR(3C),
 132 \fBrealloc\fR(3C), \fBattributes\fR(5)