Bug 86061

Summary:	Condition for read(2) to return EINVAL is inaccurate
Product:	Documentation	Reporter:	NODA, Kai (nodakai)
Component:	man-pages	Assignee:	documentation_man-pages (documentation_man-pages)
Status:	RESOLVED CODE_FIX
Severity:	normal	CC:	mtk.manpages
Priority:	P1
Hardware:	All
OS:	Linux
Kernel Version:		Subsystem:
Regression:	No	Bisected commit-id:

Description NODA, Kai 2014-10-11 19:58:04 UTC

The man page reads

> If count is greater than SSIZE_MAX, the result is unspecified.

However when we look at the implementation, rw_verify_area() which is common to vfs_read(), vfs_write() and so on actually tests if count fits ssize_t or not and returns EINVAL otherwise.

http://lxr.free-electrons.com/source/fs/read_write.c#L348

So the man page should state so.

This is also important in terms of conformance/getting closer to POSIX. 
Quotes from POSIX.1-2008:

http://pubs.opengroup.org/onlinepubs/9699919799/functions/read.html

> If the value of nbyte is greater than {SSIZE_MAX}, the result is
> implementation-defined.

where "implementation-defined" is defined as:

http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap01.html#tag_01_05_02

> Describes a value or behavior that is not defined by POSIX.1-2008 but is
> selected by an implementor. (...snip...)
> 
> The implementor shall document such a value or behavior so that it can be
> used correctly by an application.

So it cannot be just "unspecified".

Moreover, write(2) doesn't say anything about the SSIZE_MAX limit.

Comment 1 Michael Kerrisk 2017-01-25 23:10:04 UTC

Thanks for the report.

So, I've changed the text in read(2) to say:

       According to POSIX.1, if count  is  greater  than  SSIZE_MAX,  the
       result is implementation-defined; see NOTES for the upper limit on
       Linux.

Further down in that page, there is already this text:

       On  Linux, read() (and similar system calls) will transfer at most
       0x7ffff000 (2,147,479,552) bytes, returning the  number  of  bytes
       actually  transferred.   (This  is  true on both 32-bit and 64-bit
       systems.)

In write(2), I've also added this:

       According to POSIX.1, if count  is  greater  than  SSIZE_MAX,  the
       result is implementation-defined; see NOTES for the upper limit on
       Linux.

I hope this suffices. For now, I will close this bug. Please reopen, if you think more work is needed.