[src/trunk]: src/lib/libc/stdio put back the CAVEATS section

[drochner <drochner%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/5d69c20450c8
branches:  trunk
changeset: 566482:5d69c20450c8
user:      drochner <drochner%NetBSD.org@localhost>
date:      Mon May 10 17:15:28 2004 +0000

description:
put back the CAVEATS section
pointed out by wiz

diffstat:

 lib/libc/stdio/fgetln.3 |  41 ++++++++++++++++++++++++++++++++---------
 1 files changed, 32 insertions(+), 9 deletions(-)

diffs (59 lines):

diff -r 38f7a30e143f -r 5d69c20450c8 lib/libc/stdio/fgetln.3
--- a/lib/libc/stdio/fgetln.3   Mon May 10 17:03:05 2004 +0000
+++ b/lib/libc/stdio/fgetln.3   Mon May 10 17:15:28 2004 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: fgetln.3,v 1.13 2004/04/21 00:21:04 wiz Exp $
+.\"    $NetBSD: fgetln.3,v 1.14 2004/05/10 17:15:28 drochner Exp $
 .\"
 .\" Copyright (c) 1990, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -115,7 +115,6 @@
 .Sh SEE ALSO
 .Xr ferror 3 ,
 .Xr fgets 3 ,
-.Xr fgetstr 3 ,
 .Xr fopen 3 ,
 .Xr putc 3
 .Sh HISTORY
@@ -123,10 +122,34 @@
 .Fn fgetln
 function first appeared in
 .Bx 4.4 .
-.Sh NOTES
-The
-.Fn fgetln
-function is equivalent to
-.Fn fgetstr
-with a \en
-.Fa delim .
+.Sh CAVEATS
+Since the returned buffer is not a C string (it is not null terminated), a
+common practice is to replace the newline character with
+.Sq \e0 .
+However, if the last line in a file does not contain a newline,
+the returned text won't contain a newline either.
+The following code demonstrates how to deal with this problem by allocating a
+temporary buffer:
+.Bd -literal
+       char *buf, *lbuf;
+       size_t len;
+
+       lbuf = NULL;
+       while ((buf = fgetln(fp, &len))) {
+               if (buf[len - 1] == '\en')
+                       buf[len - 1] = '\e0';
+               else {
+                       if ((lbuf = (char *)malloc(len + 1)) == NULL)
+                               err(1, NULL);
+                       memcpy(lbuf, buf, len);
+                       lbuf[len] = '\e0';
+                       buf = lbuf;
+               }
+               printf("%s\en", buf);
+
+               if (lbuf != NULL) {
+                       free(lbuf);
+                       lbuf = NULL;
+               }
+       }
+.Ed