Proper coding idioms.

[yes, there ARE some systems where read and write >SSIZE_MAX work,
and physicists use those features to write huge files in one swoop]

1 files changed, 21 insertions, 1 deletions

diff --git a/lib/libc/sys/write.2 b/lib/libc/sys/write.2
index 13f87e67dd2..ce5e17a3cdb 100644
--- a/lib/libc/sys/write.2
+++ b/lib/libc/sys/write.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: write.2,v 1.14 1999/09/26 14:16:31 espie Exp $
+.\"	$OpenBSD: write.2,v 1.15 1999/09/26 16:00:35 espie Exp $
 .\"	$NetBSD: write.2,v 1.6 1995/02/27 12:39:43 cgd Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
@@ -221,6 +221,26 @@ The
 .Fn write
 function is expected to conform to
 .St -p1003.1-88 .
+.Sh CAVEATS
+Error checks should explicitly test for \-1.
+Code such as
+.Bd -literal
+	while ((nr = write(fd, buf, sizeof buf)) > 0)
+.Ed
+.Pp
+is not maximally portable, as some platforms allow for 
+.Va nbytes
+to range between
+.Dv SSIZE_MAX 
+and
+.Dv SIZE_MAX 
+\- 2, in which case the return value of an error-free
+.Nm write
+may appear as a negative number distinct from \-1.
+Proper loops should use
+.Bd -literal
+	while ((nr = write(fd, buf, sizeof buf)) != -1 && nr != 0)
+.Ed
 .Sh HISTORY
 The
 .Fn writev