Bug 15116 - revise errno documentation
Summary: revise errno documentation
Status: NEW
Alias: None
Product: Samba 4.1 and newer
Classification: Unclassified
Component: libsmbclient (show other bugs)
Version: unspecified
Hardware: All All
: P5 normal (vote)
Target Milestone: ---
Assignee: Samba QA Contact
QA Contact: Samba QA Contact
Depends on:
Reported: 2022-07-04 06:35 UTC by Harald Sitter
Modified: 2022-07-04 06:35 UTC (History)
0 users

See Also:


Note You need to log in before you can comment on or make changes to this bug.
Description Harald Sitter 2022-07-04 06:35:49 UTC
Follow up to https://bugzilla.samba.org/show_bug.cgi?id=14983

Currently there are lists of errnos in the libsmbclient header. These lists look exhaustive (but are not necessarily - bug #15088), they may go out of date as internals change (cause it's hard to keep track) and they are also not necessarily attached to a single meaning (e.g. EINVAL from bug #14983 may point at a credential error but supposedly also other invalid inputs).

Two solutions come to mind:

a) Put a note somewhere at the top "Errno listings are meant as guidance and neither exhaustive listings nor exhaustive in meaning. Implementations must be prepared to attempt error handling with any error code."

b) Prefix the @return format:

> * @return          Returns 0 on succes. Returns 1 on failure with errno set.
> *                  Errno may be and may mean:
> *                  - EBUSY Server connections are still used, Files are open or cache
> *                          could not be purged
> *                  - EBADF context == NULL

I'd go with b), it's more noise but also super obvious.

I can prepare a diff if we pick an option. Or other ideas come up, I'm open to everything :)