Replace "shall" wordings by simpler text, to not resemble a
standards document.
When saying something like "According to POSIX/ISO C, ...", if
the mentioned standard is the same one described in STANDARDS,
remove that text (it is redundant). However, if ISO C is the
main standard that describes a type, but POSIX applies further
restrictions, keep that text.
Remove pedantic notes that may only be interesting to compiler
writers.
Replace "shall" wordings by simpler text, to not resemble a
standards document.
When saying something like "According to POSIX/ISO C, ...", if
the mentioned standard is the same one described in STANDARDS,
remove that text (it is redundant). However, if ISO C is the
main standard that describes a type, but POSIX applies further
restrictions, keep that text.
Remove pedantic notes that may only be interesting to compiler
writers.
Many pages: Use STANDARDS instead of CONFORMING TO
STANDARDS seems to be much more extended than CONFORMING TO. For
consistency across the whole manual pages corpus, let's try to
unify, by following the most commonly used section name.
On 7/27/22 12:49, Ingo Schwarze wrote:
> Alejandro Colomar wrote on Tue, Jul 26, 2022 at 02:02:56PM +0200:
> > We use CONFORMING TO in Linux. Don't know why; just history, I guess.
> > See man-pages(7).
>
> Weird.
>
> I failed to find a single instance of "CONFORMING TO" in AT&T UNIX
> (including v6, PWB, v7, 32v, v8, v10, System III, SVR1, SVR2) nor in
> any version of UCB CSRG BSD. So considering that System V and BSD are
> widely considered the two main original branches of the development
> of Unix-like operating systems and Linux is often considered to have
> drawn inspiration from both, the section name "CONFORMING TO" does
> not appear to be a UNIX thing. For example, Aeleen Frisch, "Essential
> System Administration", O'Reilly, Cambridge 1995, considers Linux
> as slightly more influenced by 4.3BSD than by System V Release 3.
>
> STANDARDS, on the other hand, is present since 4.3BSD-Reno (June 1990).
>
> 4.3BSD-Reno predates the first version of the Linux kernel by more than
> a year, and the first Linux manual pages probably for longer than that.
>
> So i have no idea where "CONFORMING TO" may have come from.
Scripted change:
$ find man* -type f | xargs sed -i 's/CONFORMING TO/STANDARDS/'
The first sentence in
getsid(0) returns the session ID of the calling process.
getsid() returns the session ID of the process with process ID pid.
If pid is 0, getsid() returns the session ID of the calling process.
blames to beginning of git, duplicates the third one,
and doesn't stylistically match current formatting
CAVEATS is an interesting section. There's a slight difference
between CAVEATS and BUGS. We usually have a hard time fitting
what would go into CAVEATS into other sections (usually BUGS and
NOTES); it would be easier if we had the section. Let's add it.
This section has been used in manual pages by authors from a wide
range of projects including AT&T, Korn shell, Perl, GNU and BSD
since the early 1980s. Using the section was first officially
recommended in 2002 by the file </usr/share/misc/mdoc.template> in
NetBSD and OpenBSD.
Many pages: Use man3type/ and man2type/ for type pages
Quoting Ingo:
[
The mandoc(1) program is also able to handle paths like
"man3/id_t.3type". It will consider that page to be *both* in section
"3" (as specified by the directory name) and in section "3type" (as
specified by the file name and by the .TH macro). I would consider
it better style to keep section names consistent, i.e. to use either
"man3/id_t.3" .TH id_t 3 or "man3type/id_t.3type" .TH id_t 3type,
but it's not a big deal: since many systems (in particular various
Linux distros) suffer from such inconsistencies, handling such
inconsistencies gracefully is an important feature that certainly
won't get removed.
]
Let's be nice, and do things right here, in the hope that others
may follow the example.
===
Most of this patch has been scripted:
$ mkdir man2type man3type
$ find man2 | grep type$ | while read f; do mv -t man2type $f; done
$ find man3 | grep type$ | while read f; do mv -t man3type $f; done
$ grep -rl man3/.*type man* | xargs sed -i 's,man3/,man3type/,'
Apart from that, I adapted the Makefiles, and moved va_list into
the man3type subsection (it was accidentally placed in the main 3
section).
strftime.3, strftime_l.3: mention strftime_l() with .so link
POSIX.1-2008 TC2:
> [CX] The strftime_l() function shall be equivalent to the strftime()
function, except that the locale data used is from the locale
represented by locale.
> [CX] The behavior is undefined if the locale argument to strftime_l()
is the special locale object LC_GLOBAL_LOCALE or is not a valid locale
object handle.
FreeBSD timezone(3) is V7 char *timezone(int zone, int dst),
our documentation would imply it's impossible to service this type of
system portably
Indeed, glibc defines them both, and they make more sense for most
use-cases than trying to use the globals
glibc cited for __USE_MISC, tm_zone invalidation is Debian 2.33-7
POSIX cited for XSI marking is Issue 7 TC2
CSRG CD #2 contains 4.3BSD-Tahoe with both members
We currently ship an outdated (and factually misleading) version
of this description in ctime.3
Add a 'make help' target to document the features of our Makefile.
Move all documentation about installing from the README to a new
INSTALL file, following GNU coding standards. See
<https://www.gnu.org/prep/standards/html_node/Releases.html#Releases>.
INSTALL contains minimal information, and defers to 'make help'
for the rest.
Eric Biggers [Tue, 5 Jul 2022 18:36:14 +0000 (11:36 -0700)]
statx.2: correctly document STATX_ALL
Since kernel commit 581701b7efd6 ("uapi: deprecate STATX_ALL"),
STATX_ALL is deprecated. It doesn't include STATX_MNT_ID, and it won't
include any future flags. Update the man page accordingly.
Signed-off-by: Eric Biggers <ebiggers@google.com> Reviewed-by: Andreas Dilger <adilger@dilger.ca> Reviewed-by: Darrick J. Wong <djwong@kernel.org>
[alx: wfix, ffix] Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
fts.3: note that lstat(2) may also provide fts_statp
In FTS_PHYSICAL mode, it's always lstat()
In FTS_LOGICAL mode, it's stat() unless it ENOENTs
in which case it's lstat()
In FTS_PHYSICAL | FTS_COMFOLLOW mode, it's FTS_LOGICAL for path_argv
and FTS_PHYSICAL for children
FAN_RENAME is a new event type that includes information about
both old and new directory entries.
It is a successor of the two separate FAN_MOVED_TO/FROM events,
but those event types are still supported.
Reviewed-by: Matthew Bobrowski <repnop@google.com> Reviewed-by: Jan Kara <jack@suse.cz> Signed-off-by: Amir Goldstein <amir73il@gmail.com> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
FAN_REPORT_TARGET_FID adds an information record about the child
to directory entry modification events (create/delete/move).
This flag also adds sanity checks that directory modification events
(create,delete,moved) cannot be set in mask of a non-dir inode mark.
Note that while FAN_REPORT_TARGET_FID was merged to v5.17, the sanity
checks resulting in ENOTDIR were merged as fix commits ceaf69f8eadc
("fanotify: do not allow setting dirent events in mask of non-dir")
and 8698e3bab4dd ("fanotify: refine the validation checks on non-dir
inode mask") in later kernel releases.
Reviewed-by: Matthew Bobrowski <repnop@google.com> Reviewed-by: Jan Kara <jack@suse.cz> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
[alx: ffix] Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Sam James [Fri, 24 Jun 2022 02:59:11 +0000 (03:59 +0100)]
updwtmp.3: Add #define GNU_SOURCE for updwtmpx
Closes: https://bugzilla.kernel.org/show_bug.cgi?id=216168 Signed-off-by: Sam James <sam@gentoo.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
наб [Mon, 20 Jun 2022 15:25:17 +0000 (17:25 +0200)]
environ.7: align PWD with the standard
Issue 7, 8.3:
PWD
This variable shall represent an absolute pathname of the current
working directory. It shall not contain any components that are dot
or dot-dot. The value is set by the cd utility, and by the sh
utility during initialization.
projects / thirdparty / man-pages.git / log
