Subject: Linux-Activists - DOC Channel digest. 93-3-30-10:11
From: "Linux Activists" <[email-masked]>
To: "Linux-Activists" <[email-masked]>
Date: Fri, 30 Apr 1993 17:10:11 +0300

Topics:
	 Documentation of error returns

----------------------------------------------------------------------

From: [email-masked] (Ian Jackson)
Subject: Documentation of error returns
Date: Fri, 30 Apr 1993 13:02:48 +0300

Rick Sladkey writes:
> There is a basic error in almost all of the man2 pages.  They say
> "such-and-such system call returns -EACCES in such-and-such a case."
> All the systems calls actually return -1 on error and set errno with
> the error code.  I know it looks like they really do return negative
> errno values when you look at the kernel source but this is actually
> converted into -1 and errno values in the syscall library interface.

I have noticed the same thing in many of the section 2 manpages I've
been seeing/editing (and of course changing it as I went along). The
confusion is due to the fact that the sys_xxx functions in the kernel
actually _do_ return -EACCES etc.; somewhere else (the library? I
looked everywhere else ...) this gets turned into -1 and the -EACCESS
is made positive and put in errno.

> Here is how BSD man pages say it:
> 
> +-----
> | Upon successful completion, a value of 0 is returned.	 Otherwise, a value
> | of -1 is returned and errno is set to indicate an error.
> +-----

This is, presumably, in the RETURN VALUE section. The ERRORS section
should just give a list with entries EACCESS, EBUSY, etc. I've been
neglecting to state that the error code is put in errno, but I suppose
it should be stated somewhere. It seems silly, though, to put almost
identical text in every manpage; perhaps it should be in intro(2) ?

------------------------------

End of DOC Digest
*****************
-------