Thu Jul 23 02:31:56 2009 UTC ()
Mention, along with the behavior of succeeding system calls, the
normal behavior of succeeding library functions regarding errno.
(That is, they may leave arbitrary nonzero values in errno.)

Ok kleink@; related to PR lib/41567 as well as a recent thread on
tech-userlevel.


(dholland)
diff -r1.52 -r1.53 src/lib/libc/sys/intro.2
cvs diff -r1.52 -r1.53 src/lib/libc/sys/intro.2 (expand / switch to unified diff)

--- src/lib/libc/sys/intro.2 2009/06/02 13:15:41 1.52
+++ src/lib/libc/sys/intro.2 2009/07/23 02:31:56 1.53
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: intro.2,v 1.52 2009/06/02 13:15:41 pooka Exp $ 1.\" $NetBSD: intro.2,v 1.53 2009/07/23 02:31:56 dholland Exp $
2.\" 2.\"
3.\" Copyright (c) 1980, 1983, 1986, 1991, 1993 3.\" Copyright (c) 1980, 1983, 1986, 1991, 1993
4.\" The Regents of the University of California. All rights reserved. 4.\" The Regents of the University of California. All rights reserved.
5.\" 5.\"
6.\" Redistribution and use in source and binary forms, with or without 6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions 7.\" modification, are permitted provided that the following conditions
8.\" are met: 8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright 9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer. 10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the 12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution. 13.\" documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors 14.\" 3. Neither the name of the University nor the names of its contributors
@@ -54,40 +54,51 @@ is implemented as a macro which expands  @@ -54,40 +54,51 @@ is implemented as a macro which expands
54.Fa int . 54.Fa int .
55.Pp 55.Pp
56When a system call detects an error, 56When a system call detects an error,
57it returns an integer value 57it returns an integer value
58indicating failure (usually \-1) 58indicating failure (usually \-1)
59and sets the variable 59and sets the variable
60.Va errno 60.Va errno
61accordingly. 61accordingly.
62(This allows interpretation of the failure on receiving 62(This allows interpretation of the failure on receiving
63a \-1 and to take action accordingly.) 63a \-1 and to take action accordingly.)
64Successful calls never set 64Successful calls never set
65.Va errno ; 65.Va errno ;
66once set, it remains until another error occurs. 66once set, it remains until another error occurs.
67It should only be examined after an error. 67It should only be examined after an error has been reported, because
68Note that a number of system calls overload the meanings of these 68otherwise a leftover value from some previous error may be found
69error numbers, and that the meanings must be interpreted according 69instead.
70to the type and circumstances of the call. 70.Po
 71Many library functions that are not system calls also set
 72.Va errno
 73on return, in the same fashion.
 74In these cases a nonzero value may be left in
 75.Va errno
 76even upon successful return if some internal action failed.
 77.Pc
71.Pp 78.Pp
72The manual page for each system call will list some of the common 79The manual page for each system call will list some of the common
73errno codes that system call can return, but that should not be 80errno codes that system call can return, but that should not be
74considered an exhaustive list, i.e. 81considered an exhaustive list, i.e.
75a properly written program should be able to gracefully recover from 82a properly written program should be able to gracefully recover from
76any error that a system call might return. 83any error that a system call might return.
77Documenting all the error codes that a system call can return in 84Documenting all the error codes that a system call can return in
78a more specification-like manner would take more resources than 85a more specification-like manner would take more resources than
79this project has available. 86this project has available.
80.Pp 87.Pp
 88Note also that a number of system calls overload the meanings of these
 89error numbers, and that in these cases the meanings must be
 90interpreted according to the type and circumstances of the call.
 91.Pp
81The following is a complete list of the errors and their 92The following is a complete list of the errors and their
82names as given in 93names as given in
83.Aq Pa errno.h . 94.Aq Pa errno.h .
84.Bl -hang -width Ds 95.Bl -hang -width Ds
85.It Er 0 Em "Error 0" . 96.It Er 0 Em "Error 0" .
86Not used. 97Not used.
87.It Er 1 EPERM Em "Operation not permitted" . 98.It Er 1 EPERM Em "Operation not permitted" .
88An attempt was made to perform an operation limited to processes 99An attempt was made to perform an operation limited to processes
89with appropriate privileges or to the owner of a file or other 100with appropriate privileges or to the owner of a file or other
90resources. 101resources.
91.It Er 2 ENOENT Em "No such file or directory" . 102.It Er 2 ENOENT Em "No such file or directory" .
92A component of a specified pathname did not exist, or the 103A component of a specified pathname did not exist, or the
93pathname was an empty string. 104pathname was an empty string.