From: Dick Marinus Date: Sun, 18 Jan 2026 19:41:48 +0000 (+0100) Subject: Add man page section to (sys)calls X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d5848f104df6cb005268c10dcc48b81f858525d3;p=thirdparty%2Futil-linux.git Add man page section to (sys)calls --- diff --git a/libuuid/man/uuid_generate.3.adoc b/libuuid/man/uuid_generate.3.adoc index f8916eace..d29a774f3 100644 --- a/libuuid/man/uuid_generate.3.adoc +++ b/libuuid/man/uuid_generate.3.adoc @@ -61,19 +61,19 @@ uuid_generate, uuid_generate_random, uuid_generate_time, uuid_generate_time_safe The *uuid_generate*() function creates a new universally unique identifier (UUID). The uuid will be generated based on high-quality randomness from *getrandom*(2), _/dev/urandom_, or _/dev/random_ if available. If it is not available, then *uuid_generate*() will use an alternative algorithm which uses the current time, the local ethernet MAC address (if available), and random data generated using a pseudo-random generator. -The *uuid_generate_random*() function forces the use of the all-random UUID format, even if a high-quality random number generator is not available, in which case a pseudo-random generator will be substituted. Note that the use of a pseudo-random generator may compromise the uniqueness of UUIDs generated in this fashion. +The *uuid_generate_random*(3) function forces the use of the all-random UUID format, even if a high-quality random number generator is not available, in which case a pseudo-random generator will be substituted. Note that the use of a pseudo-random generator may compromise the uniqueness of UUIDs generated in this fashion. -The *uuid_generate_time*() function forces the use of the alternative algorithm which uses the current time and the local ethernet MAC address (if available). This algorithm used to be the default one used to generate UUIDs, but because of the use of the ethernet MAC address, it can leak information about when and where the UUID was generated. This can cause privacy problems in some applications, so the *uuid_generate*() function only uses this algorithm if a high-quality source of randomness is not available. To guarantee uniqueness of UUIDs generated by concurrently running processes, the uuid library uses a global clock state counter (if the process has permissions to gain exclusive access to this file) and/or the *uuidd*(8) daemon, if it is running already or can be spawned by the process (if installed and the process has enough permissions to run it). If neither of these two synchronization mechanisms can be used, it is theoretically possible that two concurrently running processes obtain the same UUID(s). To tell whether the UUID has been generated in a safe manner, use *uuid_generate_time_safe*. +The *uuid_generate_time*(3) function forces the use of the alternative algorithm which uses the current time and the local ethernet MAC address (if available). This algorithm used to be the default one used to generate UUIDs, but because of the use of the ethernet MAC address, it can leak information about when and where the UUID was generated. This can cause privacy problems in some applications, so the *uuid_generate*() function only uses this algorithm if a high-quality source of randomness is not available. To guarantee uniqueness of UUIDs generated by concurrently running processes, the uuid library uses a global clock state counter (if the process has permissions to gain exclusive access to this file) and/or the *uuidd*(8) daemon, if it is running already or can be spawned by the process (if installed and the process has enough permissions to run it). If neither of these two synchronization mechanisms can be used, it is theoretically possible that two concurrently running processes obtain the same UUID(s). To tell whether the UUID has been generated in a safe manner, use *uuid_generate_time_safe*(3). -The *uuid_generate_time_safe*() function is similar to *uuid_generate_time*(), except that it returns a value which denotes whether any of the synchronization mechanisms (see above) has been used. +The *uuid_generate_time_safe*(3) function is similar to *uuid_generate_time*(3), except that it returns a value which denotes whether any of the synchronization mechanisms (see above) has been used. The UUID is 16 bytes (128 bits) long, which gives approximately 3.4x10^38 unique values (there are approximately 10^80 elementary particles in the universe according to Carl Sagan's _Cosmos_). The new UUID can reasonably be considered unique among all UUIDs created on the local system, and among UUIDs created on other systems in the past and in the future. -The *uuid_generate_md5*() and *uuid_generate_sha1*() functions generate an MD5 and SHA1 hashed (predictable) UUID based on a well-known UUID providing the namespace and an arbitrary binary string. The UUIDs conform to V3 and V5 UUIDs per link:https://tools.ietf.org/html/rfc4122[RFC-4122]. +The *uuid_generate_md5*(3) and *uuid_generate_sha1*(3) functions generate an MD5 and SHA1 hashed (predictable) UUID based on a well-known UUID providing the namespace and an arbitrary binary string. The UUIDs conform to V3 and V5 UUIDs per link:https://tools.ietf.org/html/rfc4122[RFC-4122]. == RETURN VALUE -The newly created UUID is returned in the memory location pointed to by _out_. *uuid_generate_time_safe*() returns zero if the UUID has been generated in a safe manner, -1 otherwise. +The newly created UUID is returned in the memory location pointed to by _out_. *uuid_generate_time_safe*(3) returns zero if the UUID has been generated in a safe manner, -1 otherwise. == CONFORMING TO diff --git a/libuuid/man/uuid_parse.3.adoc b/libuuid/man/uuid_parse.3.adoc index cecabe4cf..c651f7d3c 100644 --- a/libuuid/man/uuid_parse.3.adoc +++ b/libuuid/man/uuid_parse.3.adoc @@ -55,7 +55,7 @@ uuid_parse - convert an input UUID string into binary representation The *uuid_parse*() function converts the UUID string given by _in_ into the binary representation. The input UUID is a string of the form 1b4e28ba-2fa1-11d2-883f-b9a761bde3fb (in *printf*(3) format "%08x-%04x-%04x-%04x-%012x", 36 bytes plus the trailing '\0'). -The *uuid_parse_range*() function works like *uuid_parse*() but parses only range in string specified by _in_start_ and _in_end_ pointers. +The *uuid_parse_range*(3) function works like *uuid_parse*() but parses only range in string specified by _in_start_ and _in_end_ pointers. == RETURN VALUE diff --git a/login-utils/runuser.1.adoc b/login-utils/runuser.1.adoc index 8402bfeac..d9c7e11f8 100644 --- a/login-utils/runuser.1.adoc +++ b/login-utils/runuser.1.adoc @@ -26,7 +26,7 @@ When called without arguments, *runuser* defaults to running an interactive shel For backward compatibility, *runuser* defaults to not changing the current directory and to setting only the environment variables *HOME* and *SHELL* (plus *USER* and *LOGNAME* if the target _user_ is not root). This version of *runuser* uses PAM for session management. -Note that *runuser* in all cases use PAM (pam_getenvlist()) to do the final environment modification. Command-line options such as *--login* and *--preserve-environment* affect the environment before it is modified by PAM. +Note that *runuser* in all cases use PAM (*pam_getenvlist*(3)) to do the final environment modification. Command-line options such as *--login* and *--preserve-environment* affect the environment before it is modified by PAM. Since version 2.38 *runuser* resets process resource limits RLIMIT_NICE, RLIMIT_RTPRIO, RLIMIT_FSIZE, RLIMIT_AS and RLIMIT_NOFILE. diff --git a/lsfd-cmd/lsfd.1.adoc b/lsfd-cmd/lsfd.1.adoc index 195e54d7e..f15f2340d 100644 --- a/lsfd-cmd/lsfd.1.adoc +++ b/lsfd-cmd/lsfd.1.adoc @@ -619,8 +619,8 @@ descriptor, _L_ is used as the flag. + [-m]::: Multiplexed. If the file descriptor is targeted by a eventpoll file -or classical system calls for multiplexing (*select*(), *pselect*(), *poll*(), and -*ppoll*()), this bit flag is set. Note that if an invocation of the +or classical system calls for multiplexing (*select*(2), *pselect*(2), *poll*(2), and +*ppoll*(2)), this bit flag is set. Note that if an invocation of the classical system calls is interrupted, *lsfd* may fail to mark _m_ on the file descriptors monitored by the invocation. See *restart_syscall*(2). diff --git a/misc-utils/fadvise.1.adoc b/misc-utils/fadvise.1.adoc index 4206d2ca6..28b3f3e2c 100644 --- a/misc-utils/fadvise.1.adoc +++ b/misc-utils/fadvise.1.adoc @@ -8,7 +8,7 @@ == NAME -fadvise - utility to use the posix_fadvise system call +fadvise - utility to use the *posix_fadvise*(2) system call == SYNOPSIS diff --git a/misc-utils/fincore.1.adoc b/misc-utils/fincore.1.adoc index 2d0ab248a..22154d4fd 100644 --- a/misc-utils/fincore.1.adoc +++ b/misc-utils/fincore.1.adoc @@ -25,9 +25,9 @@ fincore - count pages of file contents in core == DESCRIPTION *fincore* counts pages of file contents being resident in memory (in core), and reports the numbers. If an error occurs during counting, then an error message is printed to the stderr and *fincore* continues processing the rest of files listed in a command line. -*fincore* uses the *cachestat*(2) syscall to count resident pages. If the *cachestat* syscall is not available and *cachestat* usage is not forced with the *--cachestat* option, then *fincore* uses the *mincore*(2) syscall as a fallback. -The *cachestat* syscall is more efficient than *mincore* because it does not require a page table lock to walks page tables, and also reports more information than *mincore*, like the number of cached pages, dirty pages, pages marked for writeback, evicted pages, and recently evicted pages. -Another difference between the two syscalls is that if write permissions are not granted to the file, then *cachestat* returns an error, while *mincore* for security reasons, returns fake data as if all pages were resident in memory (c.f.r. link:https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=134fca9063ad4851de767d1768180e5dede9a881[kernel commit "make mincore() more conservative"]). +*fincore* uses the *cachestat*(2) syscall to count resident pages. If the *cachestat*(2) syscall is not available and *cachestat* usage is not forced with the *--cachestat* option, then *fincore* uses the *mincore*(2) syscall as a fallback. +The *cachestat*(2) syscall is more efficient than *mincore* because it does not require a page table lock to walks page tables, and also reports more information than *mincore*, like the number of cached pages, dirty pages, pages marked for writeback, evicted pages, and recently evicted pages. +Another difference between the two syscalls is that if write permissions are not granted to the file, then *cachestat*(2) returns an error, while *mincore*(2) for security reasons, returns fake data as if all pages were resident in memory (c.f.r. link:https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=134fca9063ad4851de767d1768180e5dede9a881[kernel commit "make mincore() more conservative"]). The default output is subject to change. So whenever possible, you should avoid using default outputs in your scripts. Always explicitly define expected columns by using *--output* _columns-list_ in environments where a stable output is required. @@ -43,7 +43,7 @@ include::man-common/in-bytes.adoc[] produce a grand total. *-C*, *--cachestat*:: -force usage of the cachestat() syscall instead of mincore(), and fail if it's not available. +force usage of the *cachestat*(2) syscall instead of *mincore*(2), and fail if it's not available. *-o*, *--output* _list_:: Define output columns. See the *--help* output to get a list of the currently supported columns. The default list of columns may be extended if _list_ is specified in the format _{plus}list_. diff --git a/misc-utils/findmnt.8.adoc b/misc-utils/findmnt.8.adoc index 2abead20c..eba34042a 100644 --- a/misc-utils/findmnt.8.adoc +++ b/misc-utils/findmnt.8.adoc @@ -91,7 +91,7 @@ The optional argument _method_ is supported only for the long variant (*--kernel + * *mountinfo* - this is the default method and it reads data from the _/proc/self/mountinfo_ file. + -* *listmount* - This is an EXPERIMENTAL method that uses the listmount() and statmount() syscalls to generate the mount table. The output may not contain all details about mount nodes (for example, SOURCE is currently missing). +* *listmount* - This is an EXPERIMENTAL method that uses the *listmount*(2) and *statmount*(2) syscalls to generate the mount table. The output may not contain all details about mount nodes (for example, SOURCE is currently missing). *-l*, *--list*:: Use the list output format. This output format is automatically enabled if the output is restricted by the *-t*, *-O*, *-S* or *-T* option and the option *--submounts* is not used or if more that one source file (the option *-F*) is specified. diff --git a/misc-utils/lsclocks.1.adoc b/misc-utils/lsclocks.1.adoc index ebe0b1353..fcbe0bdf8 100644 --- a/misc-utils/lsclocks.1.adoc +++ b/misc-utils/lsclocks.1.adoc @@ -22,7 +22,7 @@ It allows to display information like current time and resolution of clocks. Different kinds of clocks are supported. * POSIX clocks: *CLOCK_MONOTONIC*, *CLOCK_REALTIME*, *CLOCK_BOOTTIME*, etc. -* CPU clocks: *clock_getcpuclockid()*. +* CPU clocks: *clock_getcpuclockid*(3). * PTP clocks: */dev/ptp0*. * RTC clocks: */dev/rtc0*. * Auxiliary clocks: *CLOCK_AUX0*, *CLOCK_AUX1*, etc. @@ -90,7 +90,7 @@ NAME <``string``>:: Shorter, easier to read name. TIME <``number``>:: -Current clock timestamp as returned by *clock_gettime()*. +Current clock timestamp as returned by *clock_gettime*(2). ISO_TIME <``string``>:: ISO8601 formatted version of *TIME*. diff --git a/sys-utils/flock.1.adoc b/sys-utils/flock.1.adoc index 9558b2b57..d9e7a1902 100644 --- a/sys-utils/flock.1.adoc +++ b/sys-utils/flock.1.adoc @@ -83,7 +83,7 @@ Drop a lock. This is usually not required, since a lock is automatically dropped Fail if the lock cannot be acquired within _seconds_. Decimal fractional values are allowed. See the *-E* option for the exit status used. The zero number of _seconds_ is interpreted as *--nonblock*. *--fcntl*:: -Instead of *flock*(2), apply an *fcntl*(2) open file description lock (that is, using the *F_OFD_SETLK* (non-blocking) or *F_OFD_SETLKW* (blocking) commands). These locks are independent of those applied via *flock*(2), but, unlike traditional POSIX fcntl() locks (*F_SETLK*, *F_SETLKW*), have semantics matching those of *flock*(2). +Instead of *flock*(2), apply an *fcntl*(2) open file description lock (that is, using the *F_OFD_SETLK* (non-blocking) or *F_OFD_SETLKW* (blocking) commands). These locks are independent of those applied via *flock*(2), but, unlike traditional POSIX *fcntl*(2) locks (*F_SETLK*, *F_SETLKW*), have semantics matching those of *flock*(2). + This is only available on kernel versions >= 3.15. diff --git a/sys-utils/mount.8.adoc b/sys-utils/mount.8.adoc index 43d2ef9a5..56bee36f4 100644 --- a/sys-utils/mount.8.adoc +++ b/sys-utils/mount.8.adoc @@ -792,7 +792,7 @@ Allow to make a target directory (mountpoint) if it does not exist yet. The opti *X-mount.nocanonicalize*[**=**_type_]:: Allows disabling of canonicalization for mount source and target paths. By default, the `mount` command resolves all paths to their absolute paths without symlinks. However, this behavior may not be desired in certain situations, such as when binding a mount over a symlink, or a symlink over a directory or another symlink. The optional argument _type_ can be either "source" or "target" (mountpoint). If no _type_ is specified, then canonicalization is disabled for both types. This mount option does not affect the conversion of source tags (e.g. *LABEL=* or *UUID=*) and _fstab_ processing. + -The command-line option *--no-canonicalize* overrides this mount option and affects all path and tag conversions in all situations, but for backward compatibility, it does not modify open_tree syscall flags and does not allow the bind-mount over a symlink use case. +The command-line option *--no-canonicalize* overrides this mount option and affects all path and tag conversions in all situations, but for backward compatibility, it does not modify *open_tree*(2) syscall flags and does not allow the bind-mount over a symlink use case. + Note that *mount*(8) still sanitizes and canonicalizes the source and target paths specified on the command line by non-root users, regardless of the X-mount.nocanonicalize setting. diff --git a/sys-utils/nsenter.1.adoc b/sys-utils/nsenter.1.adoc index 24f9123a7..c480bdc9c 100644 --- a/sys-utils/nsenter.1.adoc +++ b/sys-utils/nsenter.1.adoc @@ -57,7 +57,7 @@ Enter all namespaces of the target process by the default _/proc//ns/{aster namespace paths. The default paths to the target process namespaces may be overridden by namespace-specific options (e.g., **--all --mount=**_path_). + -The user namespace will be ignored if the same as the caller's current user namespace. It prevents a caller that has dropped capabilities from regaining those capabilities via a call to setns(). See *setns*(2) for more details. +The user namespace will be ignored if the same as the caller's current user namespace. It prevents a caller that has dropped capabilities from regaining those capabilities via a call to *setns*(2). See the man page for more details. *-t*, *--target* _PID_:: Specify a target process to get contexts from. The paths to the contexts specified by _pid_ are: diff --git a/sys-utils/rtcwake.8.adoc b/sys-utils/rtcwake.8.adoc index 5164a23a3..601e15ece 100644 --- a/sys-utils/rtcwake.8.adoc +++ b/sys-utils/rtcwake.8.adoc @@ -91,7 +91,7 @@ Don't suspend, but read the RTC device until an alarm time appears. This mode is Disable a previously set alarm. *show*;; -Print alarm information in format: "alarm: off|on