Small rewrites in DESCRIPTION.

man3/errno.3

@@ -27,7 +27,7 @@
 .\" 2006-02-09 Kurt Wall, mtk
 .\"     Added non-POSIX errors
 .\"
-.TH ERRNO 3 2006-02-09 "" "Linux Programmer's Manual"
+.TH ERRNO 3 2008-07-09 "" "Linux Programmer's Manual"
 .SH NAME
 errno \- number of last error
 .SH SYNOPSIS
@@ -41,15 +41,29 @@ header file defines the integer variable
 .IR errno ,
 which is set by system calls and some library functions in the event
 of an error to indicate what went wrong.
-Its value is significant only when the call
-returned an error (usually \-1), and a function that does succeed
-is allowed to change
+Its value is significant only when the return value of
+the call indicated an error
+(i.e., \-1 from most system calls;
+\-1 or NULL from most library functions);
+a function that succeeds
+.I is
+allowed to change
 .IR errno .
 
-Sometimes, when \-1 is also a valid successful return value
-one has to zero
+Valid error numbers are all non-zero; \fIerrno\fP is never set to zero
+by any system call or library function.
+
+For some system calls and library functions (e.g.,
+.BR getpriority (2)),
+\-1 is a valid return on success.
+In such cases, a successful return can be distinguished from an error
+return by setting
 .I errno
-before the call in order to detect possible errors.
+to zero before the call, and then,
+if the call returns a status that indicates that an error
+may have occurred, checking to see if
+.I errno
+has a non-zero value.
 
 \fIerrno\fP is defined by the ISO C standard to be a modifiable lvalue
 of type \fIint\fP, and must not be explicitly declared; \fIerrno\fP
@@ -57,8 +71,6 @@ may be a macro.
 \fIerrno\fP is thread-local; setting it in one thread
 does not affect its value in any other thread.
 
-Valid error numbers are all non-zero; \fIerrno\fP is never set to zero
-by any library function.
 All the error names specified by POSIX.1
 must have distinct values, with the exception of
 .B EAGAIN