mingwrt/man/getline.3.man

   1 .\" vim: ft=nroff
   2 .TH %PAGEREF% MinGW "Programmer's Reference Manual"
   3 .
   4 .SH NAME
   5 .BR getline ,\0 getdelim
   6 \- read a delimited record from a stream
   7 .
   8 .
   9 .SH SYNOPSIS
  10 .B  #include
  11 .RB < stdio.h >
  12 .PP
  13 .B  ssize_t getdelim( char
  14 .BI ** linebuf ,
  15 .B  size_t
  16 .BI * n ,
  17 .B  int
  18 .IB delim ,
  19 .B  FILE
  20 .BI * stream
  21 .B  );
  22 .br
  23 .B  ssize_t getline( char
  24 .BI ** linebuf ,
  25 .B  size_t
  26 .BI * n ,
  27 .B  FILE
  28 .BI * stream
  29 .B  );
  30 .
  31 .PP
  32 .in -4n
  33 Feature Test Macro Requirements for libmingwex:
  34 .TP 4
  35 .BR getdelim (),\~ getline ():
  36 .nf
  37 Available since libmingwex version 3.22:
  38 .BR _POSIX_C_SOURCE\0 >=\0 200809L\0 ||\0 _XOPEN_SOURCE\0 >=\0 700
  39 .fi
  40 .
  41 .
  42 .SH DESCRIPTION
  43 The
  44 .BR getdelim ()
  45 function reads data from
  46 .IR stream ,
  47 until either a character entity matching
  48 .IR delim ,
  49 or
  50 .I EOF
  51 is encountered;
  52 the data so read,
  53 including the
  54 .I delim
  55 character if present,
  56 is stored into the buffer referenced by the pointer at
  57 .B *\c
  58 .IR linebuf ,
  59 and is
  60 .I NUL
  61 terminated.
  62 .PP
  63 The
  64 .BR getline ()
  65 function is a special case of
  66 .BR getdelim (),
  67 with the
  68 .I delim
  69 argument implicitly specified as the POSIX newline character,
  70 .IR '\en' .
  71 .
  72 .PP
  73 The
  74 .I linebuf
  75 argument must be a reference to a pointer which is safe to pass to
  76 .BR free ();
  77 either a
  78 .I NULL
  79 pointer,
  80 or a pointer to a buffer of size as indicated by
  81 .B *\c
  82 .IR n ,
  83 allocated by
  84 .BR malloc ().
  85 Passing a value of
  86 .I NULL
  87 in
  88 .B *\c
  89 .IR linebuf ,
  90 with a value of zero in
  91 .B *\c
  92 .IR n ,
  93 is both allowed,
  94 and recommended as a mechanism for requesting allocation
  95 of a default buffer.
  96 .
  97 .PP
  98 The
  99 .I delim
 100 argument is specified as an
 101 .BR int ;
 102 it must be passed a value which is representable as an
 103 .BR "unsigned char" ,
 104 otherwise the behaviour is undefined.
 105 .
 106 .
 107 .PP
 108 If
 109 .BI * linebuf
 110 is initially passed as a
 111 .I NULL
 112 pointer,
 113 then
 114 .BR getdelim ()
 115 or
 116 .BR getline ()
 117 will call
 118 .BR malloc (),
 119 in an attempt to allocate
 120 .BI * n
 121 bytes,
 122 or an arbitrarily sized smaller default buffer,
 123 if such an allocation is not achievable.
 124 In either case,
 125 .BI * linebuf
 126 and
 127 .BI * n
 128 will be updated to reflect the allocated buffer location,
 129 and the actual size allocated.
 130 .
 131 .PP
 132 If,
 133 at any time during collection of the input record,
 134 the buffer referenced by
 135 .BI * linebuf
 136 becomes too small to store the record,
 137 it will be expanded as necessary,
 138 and both
 139 .BI * linebuf
 140 and
 141 .BI * n
 142 will be adjusted to reflect the change in allocation.
 143 .
 144 .
 145 .SH RETURN VALUE
 146 .
 147 On successful completion,
 148 .BR getline ()
 149 and
 150 .BR getdelim ()
 151 return the number of characters stored into the buffer at
 152 .B *\c
 153 .IR linebuf ,
 154 including the
 155 .I delim
 156 character if this was encountered before
 157 .IR EOF ,
 158 but excluding the terminating
 159 .I NUL
 160 character.
 161 .
 162 .PP
 163 If no characters were read,
 164 and
 165 .I stream
 166 is at end-of-file,
 167 .BR getline ()
 168 and
 169 .BR getdelim ()
 170 return \(mi1,
 171 and the end-of-file indicator is set for
 172 .IR stream .
 173 .
 174 .PP
 175 If an error occurs,
 176 .BR getline ()
 177 and
 178 .BR getdelim ()
 179 set
 180 .IR errno ,
 181 as indicated under the heading
 182 .B ERROR CONDITIONS
 183 below,
 184 and return \(mi1.
 185 .
 186 .
 187 .SH ERROR CONDITIONS
 188 .
 189 .BR getline ()
 190 and
 191 .BR getdelim
 192 may fail for any of the reasons described as failure conditions for
 193 .BR fgetc ();
 194 when any such error occurs,
 195 .I errno
 196 is left as set by
 197 .BR fgetc (),
 198 and
 199 .BR getline ()
 200 or
 201 .BR getdelim ()
 202 returns \(mi1.
 203 .
 204 .PP
 205 In addition to
 206 .BR fgetc ()
 207 failure conditions,
 208 .BR getline ()
 209 and
 210 .BR getdelim ()
 211 may fail,
 212 returning \(mi1 after setting
 213 .I errno
 214 to indicate occurrence of any of the following errors:
 215 .
 216 .RS 4
 217 .TP 10
 218 .B EINVAL
 219 .I linebuf
 220 or
 221 .I n
 222 is
 223 .IR NULL .
 224 .
 225 .TP 10
 226 .B EBADF
 227 .I stream
 228 is a
 229 .I NULL
 230 pointer,
 231 or otherwise is not a valid stream opened for reading,
 232 as determined by
 233 .BR fgetc ().
 234 .
 235 .TP 10
 236 .B ENOMEM
 237 An attempt to allocate a buffer,
 238 or to expand the buffer referenced by
 239 .B *
 240 .IR linebuf ,
 241 was unsuccessful.
 242 .
 243 .TP 10
 244 .B ERANGE
 245 More than
 246 .B SSIZE_MAX
 247 characters were read,
 248 without finding
 249 .IR delim .
 250 (Note that POSIX specifies that
 251 .I errno
 252 should be set to
 253 .B EOVERFLOW
 254 for this error condition;
 255 see heading
 256 .B CAVEATS AND BUGS
 257 below,
 258 for the rationale for the use of
 259 .B ERANGE
 260 in this implementation).
 261 .RE
 262 .
 263 .
 264 .SH CONFORMING TO
 265 .
 266 Originally implemented as GNU extension functions,
 267 both
 268 .BR getline ()
 269 and
 270 .BR getdelim ()
 271 were adopted into POSIX.1-2008;
 272 implementations conforming to this POSIX standard have been
 273 integrated into libmingwex from version 3.22 onwards.
 274 .
 275 .
 276 .SH EXAMPLE
 277 .nf
 278 #include <stdio.h>
 279 #include <stdlib.h>
 280
 281 int main ()
 282 {
 283   FILE *fp;
 284   char *line = NULL;
 285   size_t len = 0;
 286   ssize_t count;
 287
 288   if ((fp = fopen ("/etc/motd", "r")) == NULL)
 289     exit (EXIT_FAILURE);
 290
 291   while ((count = getline (&line, &len, fp)) != -1)
 292     printf ("Retrieved line of length %zu:\en> %s\en", count, line);
 293
 294   if (ferror (fp)) { /* handle error */ }
 295
 296   free (line);
 297   fclose (fp);
 298   return 0;
 299 }
 300 .fi
 301 .
 302 .
 303 .SH CAVEATS AND BUGS
 304 .
 305 A return value of \(mi1 may indicate that
 306 .I stream
 307 is already at end-of-file when
 308 .BR getline ()
 309 or
 310 .BR getdelim ()
 311 is called,
 312 or it may indicate an error condition;
 313 use
 314 .BR ferror ()
 315 or
 316 .BR feof ()
 317 to distinguish error and end-of-file conditions.
 318 .
 319 .PP
 320 The return type of
 321 .I ssize_t
 322 can accommodate a maximum character count of
 323 .BR SSIZE_MAX ,
 324 and thus,
 325 the return value will overflow if
 326 .BR getline ()
 327 or
 328 .BR getdelim ()
 329 reads
 330 .B SSIZE_MAX
 331 characters without encountering a line delimiter;
 332 for this overflow condition,
 333 POSIX.1-2008 stipulates an
 334 .I errno
 335 condition code of
 336 .B EOVERFLOW .
 337 However,
 338 MSVCRT.DLL provides no significant interpretation for
 339 an arbitrarily assigned
 340 .B EOVERFLOW
 341 .I errno
 342 code.
 343 Thus,
 344 this implementation of
 345 .BR getline ()
 346 and
 347 .BR getdelim ()
 348 substitutes the semantically similar,
 349 (but not semantically identical),
 350 .B ERANGE
 351 .I errno
 352 code for
 353 .BR EOVERFLOW ,
 354 to ensure that MSVCRT.DLL's
 355 .BR strerror ()
 356 can return an acceptable description for this error condition.
 357 .
 358 .
 359 .SH SEE ALSO
 360 .
 361 Please refer to Microsoft's documentation,
 362 on MSDN,
 363 for standard I/O streams,
 364 .BR fgetc (),
 365 .BR ferror (),
 366 .BR feof (),
 367 .BR malloc (),
 368 .BR free (),
 369 .BR strerror (),
 370 and
 371 .BR errno .
 372 .
 373 .
 374 .SH AUTHOR
 375 .
 376 This manpage was written by \%Keith\ Marshall,
 377 \%<keithmarshall@users.sourceforge.net>, to document the
 378 .BR \%getline ()
 379 and
 380 .BR \%getdelim ()
 381 functions as they have been implemented for the MinGW.org Project.
 382 It may be copied, modified and redistributed,
 383 without restriction of copyright,
 384 provided this acknowledgement of contribution by
 385 the original author remains unchanged.
 386 .
 387 .\" EOF