From: Christian Goeschel Ndjomouo Date: Mon, 20 Apr 2026 02:05:00 +0000 (-0400) Subject: man: use symbolic link instead of symlink X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=b5298cebd851e3050a0484e12bbe0e4ef858cf00;p=thirdparty%2Futil-linux.git man: use symbolic link instead of symlink Signed-off-by: Christian Goeschel Ndjomouo --- diff --git a/libblkid/libblkid.3.adoc b/libblkid/libblkid.3.adoc index 57908d420..906352e73 100644 --- a/libblkid/libblkid.3.adoc +++ b/libblkid/libblkid.3.adoc @@ -35,7 +35,7 @@ The high-level part of the library keeps information about block devices in a ca In situations where one is getting information about a single known device, it does not impact performance whether the cache is used or not (unless you are not able to read the block device directly). -The high-level part of the library supports two methods to determine *LABEL/UUID*. It reads information directly from a block device or reads information from /dev/disk/by-* udev symlinks. The udev is preferred method by default. +The high-level part of the library supports two methods to determine *LABEL/UUID*. It reads information directly from a block device or reads information from /dev/disk/by-* udev symbolic links. The udev is preferred method by default. If you are dealing with multiple devices, use of the cache is highly recommended (even if empty) as devices will be scanned at most one time and the on-disk cache will be updated if possible. diff --git a/misc-utils/blkid.8.adoc b/misc-utils/blkid.8.adoc index 27bbbf106..8ff5fda00 100644 --- a/misc-utils/blkid.8.adoc +++ b/misc-utils/blkid.8.adoc @@ -74,7 +74,7 @@ Look up only one device that matches the search parameter specified with the *-- This option forces *blkid* to use udev when used for LABEL or UUID tokens in *--match-token*. The goal is to provide output consistent with other utils (like *mount*(8), etc.) on systems where the same tag is used for multiple devices. *-L*, *--label* _label_:: -Look up the device that uses this filesystem _label_; this is equal to **--list-one --output device --match-token LABEL=**__label__. This lookup method is able to reliably use /dev/disk/by-label udev symlinks (dependent on a setting in _/etc/blkid.conf_). Avoid using the symlinks directly; it is not reliable to use the symlinks without verification. The *--label* option works on systems with and without udev. +Look up the device that uses this filesystem _label_; this is equal to **--list-one --output device --match-token LABEL=**__label__. This lookup method is able to reliably use /dev/disk/by-label udev symbolic links (dependent on a setting in _/etc/blkid.conf_). Avoid using the symbolic links directly; it is not reliable to use the symbolic links without verification. The *--label* option works on systems with and without udev. + Unfortunately, the original *blkid*(8) from e2fsprogs uses the *-L* option as a synonym for *-o list*. For better portability, use **-l -o device -t LABEL=**__label__ and *-o list* in your scripts rather than the *-L* option. @@ -164,13 +164,13 @@ If an ambivalent probing result was detected by low-level probing mode (*-p*), a The standard location of the _/etc/blkid.conf_ config file can be overridden by the environment variable *BLKID_CONF*. The following options control the libblkid library: _SEND_UEVENT=_:: -Sends uevent when _/dev/disk/by-{label,uuid,partuuid,partlabel}/_ symlink does not match with LABEL, UUID, PARTUUID or PARTLABEL on the device. Default is "yes". +Sends uevent when _/dev/disk/by-{label,uuid,partuuid,partlabel}/_ symbolic link does not match with LABEL, UUID, PARTUUID or PARTLABEL on the device. Default is "yes". _CACHE_FILE=_:: Overrides the standard location of the cache file. This setting can be overridden by the environment variable *BLKID_FILE*. Default is _/run/blkid/blkid.tab_, or _/etc/blkid.tab_ on systems without a _/run_ directory. _EVALUATE=_:: -Defines LABEL and UUID evaluation method(s). Currently, the libblkid library supports the "udev" and "scan" methods. More than one method may be specified in a comma-separated list. Default is "udev,scan". The "udev" method uses udev _/dev/disk/by-*_ symlinks and the "scan" method scans all block devices from the _/proc/partitions_ file. +Defines LABEL and UUID evaluation method(s). Currently, the libblkid library supports the "udev" and "scan" methods. More than one method may be specified in a comma-separated list. Default is "udev,scan". The "udev" method uses udev _/dev/disk/by-*_ symbolic links and the "scan" method scans all block devices from the _/proc/partitions_ file. == ENVIRONMENT diff --git a/misc-utils/namei.1.adoc b/misc-utils/namei.1.adoc index 0e6f1f0c2..2548071f2 100644 --- a/misc-utils/namei.1.adoc +++ b/misc-utils/namei.1.adoc @@ -63,7 +63,7 @@ Use the long listing format (same as *-m -o -v*). Show the mode bits of each file type in the style of *ls*(1), for example 'rwxr-xr-x'. *-n*, *--nosymlinks*:: -Don't follow symlinks. +Don't follow symbolic links. *-o*, *--owners*:: Show owner and group name of each file. diff --git a/misc-utils/rename.1.adoc b/misc-utils/rename.1.adoc index 6f0abba6f..814f49ef6 100644 --- a/misc-utils/rename.1.adoc +++ b/misc-utils/rename.1.adoc @@ -29,7 +29,7 @@ rename - rename files == OPTIONS *-s*, *--symlink*:: -Do not rename a symlink but change where it points. +Do not rename a symbolic link but change where it points. *-v*, *--verbose*:: Show which files were renamed, if any. @@ -44,7 +44,7 @@ Replace all occurrences of _substring_ rather than only the first one. Replace the last occurrence of _substring_ rather than the first one. *-o*, *--no-overwrite*:: -Do not overwrite existing files. When *--symlink* is active, do not overwrite symlinks pointing to existing targets. +Do not overwrite existing files. When *--symlink* is active, do not overwrite symbolic links pointing to existing targets. *-i*, *--interactive*:: Ask before overwriting existing files. diff --git a/sys-utils/mount.8.adoc b/sys-utils/mount.8.adoc index 3f9a90877..08f49f763 100644 --- a/sys-utils/mount.8.adoc +++ b/sys-utils/mount.8.adoc @@ -126,7 +126,7 @@ The command *lsblk --fs* provides an overview of filesystems, LABELs and UUIDs o Don't forget that there is no guarantee that UUIDs and labels are really unique, especially if you move, share or copy the device. Use *lsblk -o +UUID,PARTUUID* to verify that the UUIDs are really unique in your system. -The recommended setup is to use tags (e.g. *UUID*=_uuid_) rather than _/dev/disk/by-{label,uuid,id,partuuid,partlabel}_ udev symlinks in the _/etc/fstab_ file. Tags are more readable, robust and portable. The *mount*(8) command internally uses udev symlinks, so the use of symlinks in _/etc/fstab_ has no advantage over tags. For more details see *libblkid*(3). +The recommended setup is to use tags (e.g. *UUID*=_uuid_) rather than _/dev/disk/by-{label,uuid,id,partuuid,partlabel}_ udev symbolic links in the _/etc/fstab_ file. Tags are more readable, robust and portable. The *mount*(8) command internally uses udev symbolic links, so the use of symbolic links in _/etc/fstab_ has no advantage over tags. For more details see *libblkid*(3). The _proc_ filesystem is not associated with a special device, and when mounting it, an arbitrary keyword - for example, __proc__ - can be used instead of a device specification. (The customary choice _none_ is less fortunate: the error message 'none already mounted' from *mount* can be confusing.) @@ -144,7 +144,7 @@ ____ When mounting a filesystem mentioned in _fstab_ or _mtab_, it suffices to specify on the command line only the device, or only the mount point. -The programs *mount* and *umount*(8) traditionally maintained a list of currently mounted filesystems in the file _/etc/mtab_. The support for regular classic _/etc/mtab_ is completely disabled at compile time by default, because on current Linux systems it is better to make _/etc/mtab_ a symlink to _/proc/mounts_ instead. The regular _mtab_ file maintained in userspace cannot reliably work with namespaces, containers and other advanced Linux features. If the regular _mtab_ support is enabled, then it's possible to use the file as well as the symlink. +The programs *mount* and *umount*(8) traditionally maintained a list of currently mounted filesystems in the file _/etc/mtab_. The support for regular classic _/etc/mtab_ is completely disabled at compile time by default, because on current Linux systems it is better to make _/etc/mtab_ a symbolic link to _/proc/mounts_ instead. The regular _mtab_ file maintained in userspace cannot reliably work with namespaces, containers and other advanced Linux features. If the regular _mtab_ support is enabled, then it's possible to use the file as well as the symbolic link. If no arguments are given to *mount*, the list of mounted filesystems is printed. @@ -790,9 +790,9 @@ ____ Allow to make a target directory (mountpoint) if it does not exist yet. The optional argument _mode_ specifies the filesystem access mode used for *mkdir*(2) in octal notation. The default mode is 0755. This functionality is supported only for root users or when *mount* is executed without suid permissions. The option is also supported as *x-mount.mkdir*, but this notation is deprecated since v2.30. See also *--mkdir* command line option. *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. +Allows disabling of canonicalization for mount source and target paths. By default, the `mount` command resolves all paths to their absolute paths without symbolic links. However, this behavior may not be desired in certain situations, such as when binding a mount over a symbolic link, or a symbolic link over a directory or another symbolic link. 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*(2) 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 symbolic link 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. @@ -843,7 +843,7 @@ The user namespace will then be attached to the mount and the ID-mapping of the For example, *X-mount.idmap=/proc/PID/ns/user* will attach the user namespace of the process PID to the mount. *nosymfollow*:: -Do not follow symlinks when resolving paths. Symlinks can still be created, and *readlink*(1), *readlink*(2), *realpath*(1), and *realpath*(3) all still work properly. +Do not follow symbolic links when resolving paths. Symbolic links can still be created, and *readlink*(1), *readlink*(2), *realpath*(1), and *realpath*(3) all still work properly. == FILESYSTEM-SPECIFIC MOUNT OPTIONS @@ -1776,13 +1776,13 @@ _/run/mount_:: libmount private runtime directory _/etc/mtab_:: -table of mounted filesystems or symlink to _/proc/mounts_ +table of mounted filesystems or symbolic link to _/proc/mounts_ _/etc/mtab~_:: -lock file (unused on systems with _mtab_ symlink) +lock file (unused on systems with _mtab_ symbolic link) _/etc/mtab.tmp_:: -temporary file (unused on systems with _mtab_ symlink) +temporary file (unused on systems with _mtab_ symbolic link) _/etc/filesystems_:: a list of filesystem types to try @@ -1799,7 +1799,7 @@ Some Linux filesystems don't support *-o sync* and *-o dirsync* (the ext2, ext3, The *-o remount* may not be able to change mount parameters (all _ext2fs_-specific parameters, except *sb*, are changeable with a remount, for example, but you can't change *gid* or *umask* for the _fatfs_). -It is possible that the files _/etc/mtab_ and _/proc/mounts_ don't match on systems with a regular _mtab_ file. The first file is based only on the *mount* command options, but the content of the second file also depends on the kernel and others settings (e.g. on a remote NFS server -- in certain cases the *mount* command may report unreliable information about an NFS mount point and the _/proc/mount_ file usually contains more reliable information.) This is another reason to replace the _mtab_ file with a symlink to the _/proc/mounts_ file. +It is possible that the files _/etc/mtab_ and _/proc/mounts_ don't match on systems with a regular _mtab_ file. The first file is based only on the *mount* command options, but the content of the second file also depends on the kernel and others settings (e.g. on a remote NFS server -- in certain cases the *mount* command may report unreliable information about an NFS mount point and the _/proc/mount_ file usually contains more reliable information.) This is another reason to replace the _mtab_ file with a symbolic link to the _/proc/mounts_ file. Checking files on NFS filesystems referenced by file descriptors (i.e. the *fcntl* and *ioctl* families of functions) may lead to inconsistent results due to the lack of a consistency check in the kernel even if the *noac* mount option is used. diff --git a/sys-utils/mountpoint.1.adoc b/sys-utils/mountpoint.1.adoc index 34d9cfff0..9603131ab 100644 --- a/sys-utils/mountpoint.1.adoc +++ b/sys-utils/mountpoint.1.adoc @@ -35,7 +35,7 @@ Do not follow symbolic link if it the last element of the _directory_ path. Show the major/minor numbers of the given blockdevice on standard output. *--show*:: -Print the mountpoint path for the given path. This resolves the given directory or file to its actual mountpoint, which is useful with bind mounts, symlinks, or paths within filesystems. This option requires kernel support for the *statmount*(2) system call (Linux 6.8 and newer). On older kernels, this option will fail with an error message. +Print the mountpoint path for the given path. This resolves the given directory or file to its actual mountpoint, which is useful with bind mounts, symbolic links, or paths within filesystems. This option requires kernel support for the *statmount*(2) system call (Linux 6.8 and newer). On older kernels, this option will fail with an error message. include::man-common/help-version.adoc[] diff --git a/sys-utils/umount.8.adoc b/sys-utils/umount.8.adoc index 913c61d66..e50611a98 100644 --- a/sys-utils/umount.8.adoc +++ b/sys-utils/umount.8.adoc @@ -56,7 +56,7 @@ Note that a filesystem cannot be unmounted when it is 'busy' - for example, when All of the filesystems described in _/proc/self/mountinfo_ (or in deprecated _/etc/mtab_) are unmounted, except the proc, devfs, devpts, sysfs, rpc_pipefs and nfsd filesystems. This list of the filesystems may be replaced by *--types* umount option. *-A*, *--all-targets*:: -Unmount all mountpoints in the current mount namespace for the specified filesystem. The filesystem can be specified by one of the mountpoints or the device name (or UUID, etc.). When this option is used together with *--recursive*, then all nested mounts within the filesystem are recursively unmounted. This option is only supported on systems where _/etc/mtab_ is a symlink to _/proc/mounts_. +Unmount all mountpoints in the current mount namespace for the specified filesystem. The filesystem can be specified by one of the mountpoints or the device name (or UUID, etc.). When this option is used together with *--recursive*, then all nested mounts within the filesystem are recursively unmounted. This option is only supported on systems where _/etc/mtab_ is a symbolic link to _/proc/mounts_. *-c*, *--no-canonicalize*:: Do not canonicalize paths. The paths canonicalization is based on *stat*(2) and *readlink*(2) system calls. These system calls may hang in some cases (for example on NFS if server is not available). The option has to be used with canonical path to the mount point. @@ -74,7 +74,7 @@ Causes everything to be done except for the actual system call or umount helper *-f*, *--force*:: Force an unmount (in case of an unreachable NFS system). + -Note that this option does not guarantee that umount command does not hang. It's strongly recommended to use absolute paths without symlinks to avoid unwanted *readlink*(2) and *stat*(2) system calls on unreachable NFS in *umount*. +Note that this option does not guarantee that umount command does not hang. It's strongly recommended to use absolute paths without symbolic links to avoid unwanted *readlink*(2) and *stat*(2) system calls on unreachable NFS in *umount*. *-i*, *--internal-only*:: Do not call the **/sbin/umount.**__filesystem__ helper even if it exists. By default such a helper program is called if it exists. @@ -199,7 +199,7 @@ Override the default location of the _fstab_ file (ignored for *suid*). == FILES _/etc/mtab_:: -table of mounted filesystems (deprecated and usually replaced by symlink to _/proc/mounts_) +table of mounted filesystems (deprecated and usually replaced by symbolic link to _/proc/mounts_) _/etc/fstab_:: table of known filesystems