From: Paul Eggert Date: Fri, 15 Aug 2025 04:08:00 +0000 (-0700) Subject: realpath: improve doc and NEWS X-Git-Tag: v9.8~106 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=ae6fd2b4a1ff390c61f29b3d98d842ad345033a5;p=thirdparty%2Fcoreutils.git realpath: improve doc and NEWS --- diff --git a/NEWS b/NEWS index cc4a913039..d0bd06d4ad 100644 --- a/NEWS +++ b/NEWS @@ -70,27 +70,11 @@ GNU coreutils NEWS -*- outline -*- pretended that standard input was not a tty. [This bug was present in "the beginning".] -** Changes in behavior - - readlink now defaults to being verbose if the POSIXLY_CORRECT - environment variable is set. - ** New Features basenc supports the --base58 option to encode and decode the visually unambiguous Base58 encoding. - realpath supports the -E option as required by POSIX. The behavior is - the same as realpath with no options. The corresponding long option - is --canonicalize. - - tsort now accepts and ignores -w, to conform to POSIX.1-2024. - -** Improvements - - 'factor' is now much faster at identifying large prime numbers, - and significantly faster on composite numbers greater than 2^128. - stty supports setting arbitrary baud rates on supported systems, like Hurd, Linux with glibc >= 2.42, and some BSDs. Also on other systems the full set of supported baud rates @@ -100,6 +84,21 @@ GNU coreutils NEWS -*- outline -*- Iranian locale (fa_IR) and for the Ethiopian locale (am_ET), and also does so more consistently for the Thailand locale (th_TH.UTF-8). +** Changes to conform better to POSIX.1-2024 + + readlink now defaults to being verbose if the POSIXLY_CORRECT + environment variable is set. + + realpath now supports -E, which specifies the default behavior. + The corresponding long option is --canonicalize. + + tsort now accepts and ignores -w. + +** Performance improvements + + 'factor' is now much faster at identifying large prime numbers, + and significantly faster on composite numbers greater than 2^128. + ** Build-related cksum was not compilable by Apple LLVM 10.0.0 x86-64, which diff --git a/doc/coreutils.texi b/doc/coreutils.texi index 9038979b4b..c4dd2f60dd 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -15006,13 +15006,20 @@ Exit status: @pindex realpath @findex realpath -@command{realpath} expands all symbolic links and resolves references to -@samp{/./}, @samp{/../} and extra @samp{/} characters. Synopsis: +The @command{realpath} command outputs a file's canonicalized name, +which is an absolute file name that contains neither unnecessary +@samp{/} nor components that are @samp{.}, @samp{..}, or a symbolic link. + +Synopsis: @example realpath [@var{option}]@dots{} @var{file}@dots{} @end example +By default, @command{realpath} succeeds if every file name component +but the last names an existing directory. It ignores trailing slashes +that are not also leading slashes. + The file name canonicalization functionality overlaps with that of the @command{readlink} command. This is the preferred command for canonicalization as it's a more suitable and standard name. In addition @@ -15027,21 +15034,17 @@ The program accepts the following options. Also see @ref{Common options}. @opindex -E @opindex --canonicalize -Ensure all but the last component of the specified file name exist. -Otherwise, @command{realpath} will output a diagnostic unless the -@option{-q} option is specified, and exit with a nonzero exit code. A -trailing slash is ignored. This option is the default behavior, but is -included for POSIX compatibility. +Do not fail merely because the named file does not exist. +Although this is the default behavior of GNU @code{realpath}, +POSIX does not require this default, so portable applications should +use an explicit @option{-E}. @item -e @itemx --canonicalize-existing @opindex -e @opindex --canonicalize-existing -Ensure that all components of the specified file names exist. -If any component is missing or unavailable, @command{realpath} will output -a diagnostic unless the @option{-q} option is specified, and exit with a -nonzero exit code. A trailing slash requires that the name resolve to a -directory. +Fail if the named file does not exist. +A trailing slash requires that the name resolve to a directory. @item -m @itemx --canonicalize-missing @@ -15128,8 +15131,8 @@ By default, @command{realpath} prints the absolute file name of given files @example @group cd /home/user -realpath /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt -@result{} /usr/bin/sort +realpath /usr/bin/ ///tmp/.//foo /usr/share/dict/words 1.txt +@result{} /usr/bin @result{} /tmp/foo @result{} /usr/share/dict/american-english @result{} /home/user/1.txt @@ -15142,8 +15145,8 @@ the given directory: @example @group realpath --relative-to=/usr/bin \ - /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt -@result{} sort + /usr/bin/ ///tmp/.//foo /usr/share/dict/words 1.txt +@result{} . @result{} ../../tmp/foo @result{} ../share/dict/american-english @result{} ../../home/user/1.txt @@ -15157,8 +15160,8 @@ base directory absolute file names are printed: @example @group realpath --relative-base=/usr \ - /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt -@result{} bin/sort + /usr/bin/ ///tmp/.//foo /usr/share/dict/words 1.txt +@result{} bin @result{} /tmp/foo @result{} share/dict/american-english @result{} /home/user/1.txt @@ -15173,8 +15176,8 @@ printed as absolute file names: @example @group realpath --relative-to=/usr/bin --relative-base=/usr \ - /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt -@result{} sort + /usr/bin/ ///tmp/.//foo /usr/share/dict/words 1.txt +@result{} . @result{} /tmp/foo @result{} ../share/dict/american-english @result{} /home/user/1.txt