Bug 75711
| Summary: | [patch] opendir(3) missing ERRORS section | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | abc <abc> | ||||
| Component: | Manual Pages | Assignee: | Gordon Bergling <gbe> | ||||
| Status: | Closed FIXED | ||||||
| Severity: | Affects Some People | CC: | doc, gbe | ||||
| Priority: | Normal | Keywords: | patch | ||||
| Version: | Latest | ||||||
| Hardware: | Any | ||||||
| OS: | Any | ||||||
| See Also: | https://reviews.freebsd.org/D25892 | ||||||
| Attachments: |
|
||||||
|
Description
abc
2005-01-01 21:20:15 UTC
abc@ai1.anchorage.mtaonline.net wrote: > man opendir(), only the closedir() info states errno settings. The opendir() implementation in libc calls the following functions or systems calls that may fail: close(), fcntl(), fstat(), malloc(), mergesort(), open(), stat(), reallocf(). Should we document the join of all the possible errors these calls may fail with in opendir()'s manpage? > abc@ai1.anchorage.mtaonline.net wrote: > > man opendir(), only the closedir() info states errno settings. > The opendir() implementation in libc calls the following functions or > systems calls that may fail: close(), fcntl(), fstat(), malloc(), > mergesort(), open(), stat(), reallocf(). > Should we document the join of all the possible errors these calls may > fail with in opendir()'s manpage? the manpage should at LEAST state that it sets the extern "errno", otherwise, it is assumed it doesn't, and this assumption can easily result in programming catastrophies. if "errno" is not documented, and thus, not checked for in a program, "errno" will get trapped by some other function that does check for it. all calls that may set "errno" should explicity say so - so programmers can check for it after a call. thank you. Responsible Changed From-To: freebsd-doc->keramida I'll work on adding a proper ERRORS section to opendir(3). Here's a patch that cleans up some of directory(3). I've tested the errors and actually encountered a case where you can get EFAULT returned from stat() since the call just passes along blindly a NULL argument if you gave that to opendir() as dirname argument. Also attached is a short-circuit for that case in libc/gen/diropen.c. I think it makes sense to return ENOENT for that case since it fits the description. I've also renamed filename to dirname to more accurately reflect what the call operates on. For the wording of the added text I used the SUS texts, since I understand we have permission to do that nowadays. This manual page will need further cleanups, most likely resulting in the splitting of some calls to their own pages to keep the layout sane enough to follow. Please add a [patch] in front of the PR's synopsis. -- Jeroen Ruigrok van der Werven <asmodai(-at-)in-nomine.org> / asmodai ã¤ã§ã«ã¼ã³ ã©ã¦ããã㯠ã´ã¡ã³ ãã« ã¦ã§ã«ã´ã§ã³ http://www.in-nomine.org/ | http://www.rangaku.org/ All conditioned things are impermanent. Work out your own salvation with diligence... Release to wild. A commit references this bug: Author: gbe Date: Tue Aug 4 08:46:29 UTC 2020 New revision: 363829 URL: https://svnweb.freebsd.org/changeset/base/363829 Log: directory(3): Add an ERRORS section - Add an ERRORS section for opendir(3) and closedir(3) - Document also the errors of readdir(3), readdir_r(3) and telldir(3) - Convert the code sample into an EXAMPLES section PR: 75711 Submitted by: abc <abc at ai1 dot anchorage dot mtaonline dot net> Reviewed by: 0mp, bcr, jilles Approved by: 0mp, bcr, jilles Obtained from: partial from OpenBSD MFC after: 1 week Differential Revision: https://reviews.freebsd.org/D25892 Changes: head/lib/libc/gen/directory.3 Committed in parts, thanks for the patch! A commit references this bug: Author: gbe Date: Tue Aug 11 10:56:44 UTC 2020 New revision: 364106 URL: https://svnweb.freebsd.org/changeset/base/364106 Log: MFC r363829: directory(3): Add an ERRORS section - Add an ERRORS section for opendir(3) and closedir(3) - Document also the errors of readdir(3), readdir_r(3) and telldir(3) - Convert the code sample into an EXAMPLES section PR: 75711 Submitted by: abc <abc at ai1 dot anchorage dot mtaonline dot net> Reviewed by: 0mp, bcr, jilles Approved by: 0mp, bcr, jilles Obtained from: partial from OpenBSD Differential Revision: https://reviews.freebsd.org/D25892 Changes: _U stable/12/ stable/12/lib/libc/gen/directory.3 |
