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.
FAN_FS_ERROR is a new event for fanotify to report filesystem errors
that might lead to some corruption.
This documents how to use the feature and specific caveats.
Reviewed-by: Jan Kara <jack@suse.cz> Reviewed-by: Amir Goldstein <amir73il@gmail.com> Reviewed-by: Matthew Bobrowski <repnop@google.com> Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
наб [Wed, 15 Jun 2022 16:39:14 +0000 (18:39 +0200)]
uname.2: deweirdify
The NOTES were not only weirdly reductionist, but also highly
opinionated in the wrong direction.
Yes, it's a syscall in SysIII; not in 4.4BSD.
Well, in general, it exists in 4.4BSD for obvious conformace reasons.
No, it doesn't "know" (and if it does, that's not relevant),
historically and practically this is the broad CPU/machine type
(compare uname -p on SysVr4 (=> SunOS 5 => NetBSD),
which is the actual CPU model (usually)).
Everywhere, ex. def., the nodename is what the BSD calls the hostname.
"No standard" also speaks of sethostname(), so.
Historical precedent (i.e. all implementations, save *maybe* for weirdo
XENIX, who cares about weirdo XENIX) defines the hostname to be uname -n
(indeed, SVr3 uname -S sets /both/ nodename /and/ sysname!
that's not relevant here;
SunOS gets it from the network (unless configured manually)).
Someone clearly cited SysVr4's "Internet hostnames" comment w/o credit;
fix that.
8-byte truncation is really quite secondary here (indeed, that's what
SysVr4 does for pre-SysVr4 uname() callers that haven't been rebuilt.
you will never encounter it).
The hostname is not meaningless, obviously??
Also fix machine to say "hardware type", like the standard;
"hardware identifier" would be hostid. I wrote six seething pages about
hostid, and machine is /not/ hostid.
наб [Wed, 15 Jun 2022 16:39:09 +0000 (18:39 +0200)]
uname.2: fix standard reference wording
Issue 6:
IEEE Std 1003.1-2001/Cor 2-2004, item XBD/TC2/D6/27 is applied,
changing the description of nodename within the utsname structure from
``an implementation-defined communications network'' to
``the communications network to which this node is attached, if any''.
These pages are not exactly what man3 typically contains, which is
library functions. Instead, types fit better in a subsection of
man3, and some UNIX systems have already a section 3type, so let's
use the same name.
Adapt the Makefile to work with this subsection. Except for the
Makefile, these changes are scripted.
Scripted changes:
$ find man3 -type f \
| grep '_t\.3$' \
| while read f; do
mv $f ${f}type;
done;
$ find man? -type f \
| xargs grep -l '^\.so.*_t\.3' \
| xargs sed -i '/^\.so/s/\.3$/\.3type/';
Mike Kravetz [Thu, 9 Jun 2022 18:52:01 +0000 (11:52 -0700)]
madvise.2: Clarify addr/length and update hugetlb support
Clarify that madvise only works on full pages, and remove references
to 'bytes'.
Update MADV_DONTNEED and MADV_REMOVE sections to remove notes that
HugeTLB mappings are not supported. Indicate the releases when they
were first supported as well as alignment restrictions.
Signed-off-by: Mike Kravetz <mike.kravetz@oracle.com> Acked-by: Peter Xu <peterx@redhat.com>
[alx: wsfix] Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
mount_setattr.2: update conditions to create ID-mapped mounts
Newer kernels in principle support the creation of ID-mapped mounts for
filesystems mountable in non-initial user namespaces. Currently, no such
filesystem has been ported to support this though. But we should
nonetheless update the conditions.
Signed-off-by: Christian Brauner (Microsoft) <brauner@kernel.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
(I think that there is at least on bug in that page, since the
notification pipe has to be opened with O_NOTIFICATION_PIPE which is
defined to O_EXCL not O_TMPFILE)
The ENOPKG error should be clear from this header (see
watch_queue_init() at the end):
update_timestamps.sh: Add script to update the pages' timestamps
This differs from what was being done until now. Before, we were
updating the timestamp with the date of the release, but that's
unnecessarily unprecise. With this, we have the actual date of
when the last change was committed.
David Ward [Mon, 6 Jun 2022 03:31:39 +0000 (23:31 -0400)]
poll.2: Set fd to its bitwise complement to ignore
A valid file descriptor will be non-negative, i.e., 0 <= fd <= INT_MAX.
When all of the bits of a valid file descriptor are flipped, the result
is a negative value: ~0 = -1, ~1 = -2, ..., ~INT_MAX = INT_MIN. If all
of these bits are flipped again, then the file descriptor is recovered.
Negating the file descriptor does not quite achieve this, because there
will be no change for fd 0. (Likewise, negating INT_MIN would not cause
any change in value, but it is never a valid file descriptor.)
Change "supported only since" to "support was added in".
Previously, this said, "MAP_POPULATE is supported for private mappings only
since Linux 2.6.23." This could be parsed as "MAP_POPULATE is supported
for private mappings only [not shared mappings] since Linux 2.6.23."
Someone (a native English speaker) tried to tell me this.
Change to "Support for MAP_POPULATE in conjunction with private mappings
was added in Linux 2.6.23." This is unambiguous, and "support was
added" is more common in other man pages.
There are more instances of "supported only since", but they seem
clearer. I could send a separate patch for them if desired.
наб [Wed, 25 May 2022 19:30:04 +0000 (21:30 +0200)]
execve.2: point to exec(3) early
Most people actually want exec(3) (or one of its aliases);
the minutiae are a separate, rarer, concern, and execve(2) hijacks
man execve from all the other exec(3) aliases
(similarly to exec(1posix), but it's at least obvious in that case that
you got the wrong page)
Update the fanotify API documentation to include details on the new
FAN_REPORT_PIDFD feature. This patch also includes a generic section
describing the concept of information records which are supported by
the fanotify API.
Signed-off-by: Matthew Bobrowski <repnop@google.com> Reviewed-by: Jan Kara <jack@suse.cz> Reviewed-by: Amir Goldstein <amir73il@gmail.com>
[alx: wsfix, ffix] Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
SC2034 (warning): EX_OK appears unused.
SC2035 (info): Use ./*glob* or -- *glob* so names with dashes
won't become options.
SC2068 (error): Double quote array expansions to avoid
re-splitting elements.
SC2086 (info): Double quote to prevent globbing and word
splitting.
SC2112 (warning): 'function' keyword is non-standard. Delete it.
SC2124 (warning): Assigning an array to a string! Assign as
array, or use * instead of @ to concatenate.
SC3001 (warning): In POSIX sh, process substitution is undefined.
SC3006 (warning): In POSIX sh, standalone ((..)) is undefined.
Also, remove unnecessary braces, and update copyright.
grepc(1) has some of the features implemented in our bash_aliases,
and then some. It also is shorter to type, and has a rich set of
command line options.
Theodore Dubois [Tue, 10 May 2022 22:08:21 +0000 (15:08 -0700)]
getpriority: Only getpriority translates the priority values
The translation is needed to avoid returning a negative number from a
successful syscall, and this requirement doesn't apply to setpriority.
See the implementation of getpriority in kernel/sys.c.
The following error is harmless and normal. Ignore it.
$ sudo make install
fatal: unsafe repository ('/home/alx/src/linux/man-pages/man-pages' is owned by someone else)
To add an exception for this directory, call:
It was straight after a note that they are nonstandard functions,
which already tells the user that if portability is in mind, they
shouldn't be used, so this recommendation adds nothing in that
sense.
Also, there's a note that timelocal() should _never_ be used, due
to mktime() being identical and in the POSIX standard (it is also
in C99), so this note would also add nothing in that sense.
So the only uses not covered by those other notes are non-portable
uses of timegm(3). In that scenario, it is an excellent function.
Cc: Paul Eggert <eggert@cs.ucla.edu> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
scripts/append_COLOPHON.sh: Add script to append the COLOPHON section
I first implemented it using cat <<-, but sed(1) is around 5 times
faster, so even if it's a bit more complex and slightly less
readable, let's use sed(1).