mingwrt/man/getline.3.man

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