svn commit: r362685 - stable/12/lib/libc/stdio

[Gordon Bergling]

Author: gbe (doc committer)
Date: Sat Jun 27 13:55:38 2020
New Revision: 362685
URL: https://svnweb.freebsd.org/changeset/base/362685

Log:
  MFC r362326: fgetln(3): Add a Caveats Section
  
  Reviewed by:	yuripv, bcr (mentor)
  Approved by:	bcr (mentror)
  Obtained from:	OpenBSD
  Differential Revision:	https://reviews.freebsd.org/D24916

Modified:
  stable/12/lib/libc/stdio/fgetln.3
Directory Properties:
  stable/12/   (props changed)

Modified: stable/12/lib/libc/stdio/fgetln.3
==============================================================================
--- stable/12/lib/libc/stdio/fgetln.3	Sat Jun 27 13:33:31 2020	(r362684)
+++ stable/12/lib/libc/stdio/fgetln.3	Sat Jun 27 13:55:38 2020	(r362685)
@@ -28,7 +28,7 @@
 .\"     @(#)fgetln.3	8.3 (Berkeley) 4/19/94
 .\" $FreeBSD$
 .\"
-.Dd February 15, 2016
+.Dd June 11, 2020
 .Dt FGETLN 3
 .Os
 .Sh NAME
@@ -126,3 +126,33 @@ The
 .Fn fgetln
 function first appeared in
 .Bx 4.4 .
+.Sh CAVEATS
+Since the returned buffer is not a C string (it is not NUL 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)) != NULL) {
+		if (buf[len - 1] == '\en')
+			buf[len - 1] = '\e0';
+		else {
+			/* EOF without EOL, copy and add the NUL */
+			if ((lbuf = malloc(len + 1)) == NULL)
+				err(1, NULL);
+			memcpy(lbuf, buf, len);
+			lbuf[len] = '\e0';
+			buf = lbuf;
+		}
+		printf("%s\en", buf);
+	}
+	free(lbuf);
+	if (ferror(fp))
+		err(1, "fgetln");
+.Ed