A NOTE has been added to this issue. ====================================================================== https://austingroupbugs.net/view.php?id=1457 ====================================================================== Reported By: steffen Assigned To: ajosey ====================================================================== Project: 1003.1(2016/18)/Issue7+TC2 Issue ID: 1457 Category: Shell and Utilities Type: Enhancement Request Severity: Editorial Priority: normal Status: Under Review Name: Steffen Nurpmeso Organization: User Reference: Section: Vol. 3: Shell and Utilities. Page Number: (page or range of pages) Line Number: (Line or range of lines) Interp Status: --- Final Accepted Text: ====================================================================== Date Submitted: 2021-03-09 21:21 UTC Last Modified: 2022-07-21 10:41 UTC ====================================================================== Summary: Add readlink(1) utility ======================================================================
---------------------------------------------------------------------- (0005898) geoffclare (manager) - 2022-07-21 10:41 https://austingroupbugs.net/view.php?id=1457#c5898 ---------------------------------------------------------------------- New suggested changes... On page 3194 insert new pages for readlink and realpath: <b>NAME</b><blockquote>readlink - display the contents of a symbolic link</blockquote> <b>SYNOPSIS</b><blockquote><pre>readlink <b>[</b>-n<b>]</b> <i>file</i></pre></blockquote> <b>DESCRIPTION</b><blockquote>If the <i>file</i> operand names a symbolic link, the <i>readlink</i> utility shall not follow the symbolic link when resolving <i>file</i> and shall write the contents of the symbolic link to standard output. If the <b>-n</b> option is not specified, the output to standard output shall be followed by a <newline> character. If <i>file</i> does not name a symbolic link, <i>readlink</i> shall write a diagnostic message to standard error and exit with non-zero status.</blockquote> <b>OPTIONS</b><blockquote>The <i>readlink</i> utility shall conform to [xref to XBD 12.2]. The following option shall be supported: <b>-n</b><blockquote>Do not output a trailing <newline> character.</blockquote></blockquote> <b>OPERANDS</b><blockquote><i>file</i><blockquote>A pathname of a symbolic link to be read.</blockquote></blockquote> <b>STDIN</b><blockquote>Not used.</blockquote> <b>INPUT FILES</b><blockquote>None.</blockquote> <b>ENVIRONMENT VARIABLES</b><blockquote>The following environment variables shall affect the execution of <i>readlink</i>: LANG<blockquote>Provide a default value for the internationalization variables that are unset or null. (See [xref to XBD 8.2] for the precedence of internationalization variables used to determine the values of locale categories.)</blockquote>LC_ALL<blockquote>If set to a non-empty string value, override the values of all the other internationalization variables.</blockquote>LC_CTYPE<blockquote>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as opposed to multi-byte characters in arguments).</blockquote>LC_MESSAGES<blockquote>Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</blockquote>[XSI]NLSPATH<blockquote>Determine the location of messages objects and message catalogs.[/XSI]</blockquote></blockquote> <b>ASYNCHRONOUS EVENTS</b><blockquote>Default.</blockquote> <b>STDOUT</b><blockquote>See DESCRIPTION.</blockquote> <b>STDERR</b><blockquote>The standard error shall be used only for diagnostic messages.</blockquote> <b>OUTPUT FILES</b><blockquote>None.</blockquote> <b>EXTENDED DESCRIPTION</b><blockquote>None.</blockquote> <b>EXIT STATUS</b><blockquote>The following exit values shall be returned: 0 Successful completion. >0 An error occurred.</blockquote> <b>CONSEQUENCES OF ERRORS</b><blockquote>Default.</blockquote> <b>APPLICATION USAGE</b><blockquote>None.</blockquote> <b>EXAMPLES</b><blockquote>None.</blockquote> <b>RATIONALE</b><blockquote>The <i>readlink</i> utility was added because using <tt>ls -l</tt> to obtain the contents of a symbolic link is difficult if the output includes more than one occurrence of the string " -> ". The <b>-f</b> option found in many implementations was not included, as the <i>realpath</i> utility provides equivalent functionality with a choice of behaviors.</blockquote> <b>FUTURE DIRECTIONS</b><blockquote>None.</blockquote> <b>SEE ALSO</b><blockquote>ln, ls, pwd, realpath XBD Chapter 8, Section 12.2 XSH readlink()</blockquote> <b>CHANGE HISTORY</b><blockquote>First released in Issue 8.</blockquote> <b>NAME</b><blockquote>realpath - resolve a pathname</blockquote> <b>SYNOPSIS</b><blockquote><pre>realpath <b>[</b>-E|-e<b>]</b> <i>file</i></pre></blockquote> <b>DESCRIPTION</b><blockquote>The <i>realpath</i> utility shall canonicalize the pathname specified by the <i>file</i> operand as follows: If a call to the <i>realpath</i() function with the specified pathname as its first argument would succeed, the canonicalized pathname shall be the pathname that would be returned by that <i>realpath</i() call. Otherwise: <ul> <li>If the <b>-e</b> option is specified, the canonicalization shall fail.</li> <li>If the <b>-E</b> option is specified, then if a call to the <i>realpath</i() function with the specified pathname as its first argument would encounter an error condition other than [ENOENT], the canonicalization shall fail; if the call would encounter an [ENOENT] error, <i>realpath</i> shall expand all symbolic links that would be encountered in an attempt to resolve the specified pathname using the algorithm specified in [xref to XBD 4.13 Pathname Resolution], except that any trailing <slash> characters that are not also leading <slash> characters shall be ignored. If this expansion succeeds and the path prefix of the expanded pathname resolves to an existing directory, the canonicalized pathname shall be the expanded pathname. In all other cases, the canonicalization shall fail. If the expanded pathname is not empty, does not begin with a <slash>, and has exactly one pathname component, it shall be treated as if it had a path prefix of "./".</li> <li>If no options are specified, <i>realpath</i> shall canonicalize the specified pathname in an unspecified manner such that the resulting absolute pathname does not contain any components that refer to files of type symbolic link and does not contain any components that are dot or dot-dot.</li> </ul> Upon successful canonicalization, <i>realpath</i> shall write the canonicalized pathname, followed by a <newline> character, to standard output. If canonicalization fails, or the canonicalized pathname is empty, nothing shall be written to standard output, a diagnostic message shall be written to standard error, and <i>realpath</i> shall exit with non-zero status.</blockquote> <b>OPTIONS</b><blockquote>The <i>realpath</i> utility shall conform to [xref to XBD 12.2]. The following options shall be supported: <b>-E</b><blockquote>Do not treat it as an error if attempting to resolve the last component of the canonicalized form of the <i>file</i> operand results in an [ENOENT] error condition.</blockquote><b>-e</b><blockquote>Treat it as an error if attempting to resolve the last component of the canonicalized form of the <i>file</i> operand results in an [ENOENT] error condition.</blockquote>Specifying more than one of the mutually-exclusive options <b>-E</b> and <b>-e</b> shall not be considered an error. The last option specified shall determine the behavior of the utility.</blockquote> <b>OPERANDS</b><blockquote><i>file</i><blockquote>A pathname to be canonicalized.</blockquote></blockquote> <b>STDIN</b><blockquote>Not used.</blockquote> <b>INPUT FILES</b><blockquote>None.</blockquote> <b>ENVIRONMENT VARIABLES</b><blockquote>The following environment variables shall affect the execution of <i>realpath</i>: LANG<blockquote>Provide a default value for the internationalization variables that are unset or null. (See [xref to XBD 8.2] for the precedence of internationalization variables used to determine the values of locale categories.)</blockquote>LC_ALL<blockquote>If set to a non-empty string value, override the values of all the other internationalization variables.</blockquote>LC_CTYPE<blockquote>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as opposed to multi-byte characters in arguments).</blockquote>LC_MESSAGES<blockquote>Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</blockquote>[XSI]NLSPATH<blockquote>Determine the location of messages objects and message catalogs.[/XSI]</blockquote></blockquote> <b>ASYNCHRONOUS EVENTS</b><blockquote>Default.</blockquote> <b>STDOUT</b><blockquote>See DESCRIPTION.</blockquote> <b>STDERR</b><blockquote>The standard error shall be used only for diagnostic messages.</blockquote> <b>OUTPUT FILES</b><blockquote>None.</blockquote> <b>EXTENDED DESCRIPTION</b><blockquote>None.</blockquote> <b>EXIT STATUS</b><blockquote>The following exit values shall be returned: 0 Successful completion. >0 An error occurred.</blockquote> <b>CONSEQUENCES OF ERRORS</b><blockquote>Default.</blockquote> <b>APPLICATION USAGE</b><blockquote>If neither the <b>-e</b> nor the <b>-E</b> option is specified, some implementations behave as if <b>-e</b> had been specified and others as if <b>-E</b> had been specified, but there are also implementations where the behavior differs from both of these. For example, the <i>mksh</i> shell has an internal implementation of <i>realpath</i> that canonicalizes <b>/dir/regular_file/..</b> to <b>/dir</b>, whereas the <i>realpath</i>() function would return an [ENOTDIR] error in this case. Portable applications should always specify either <b>-e</b> or <b>-E</b>.</blockquote> <b>EXAMPLES</b><blockquote>None.</blockquote> <b>RATIONALE</b><blockquote>The <i>realpath</i> utility was added in preference to a <b>-f</b> option found in some implementations of the <i>readlink</i> utility because it allows the application to specify whether or not a missing final component is to be treated as an error. The behavior with the <b>-E</b> option when <i>file</i> does not resolve (with symbolic links followed) to an existing file is not the same as simply calling <i>realpath</i>() with the path prefix of the <i>file</i> operand and writing the resulting pathname, a <slash>, and the last component of <i>file</i> to standard output. For example, if <b>/tmp/nofile</b> does not exist, and <i>file</i> is <b>A/B</b> where <b>A</b> is an existing directory and <b>B</b> is a symbolic link to <b>/tmp/nofile</b>, <i>realpath</i> with <b>-E</b> will output <b>/tmp/nofile</b>, but if <b>B</b>is a symbolic link to <b>/tmp/nofile/foo</b>, <i>realpath</i> with <b>-E</b> will treat this as an error. In both cases <tt>realpath("A/B")</tt> would fail with <i>errno</i> set to [ENOENT]. Even though <tt>realpath("A")</tt> would succeed, in neither case is anything ending <b>/B</b> the result. Trailing <slash> characters (that follow a non-<slash>) are handled differently with <b>-E</b> than with <b>-e</b>. With <b>-e</b> they are handled as for the <i>realpath</i>() function. With <b>-E</b> they are sometimes effectively ignored, and they are never included in the output. For example, if <b>/tmp/nofile</b> does not exist and <b>/tmp/regfile</b> is an existing regular file:<pre>$ realpath -E /tmp/nofile/ /tmp/nofile $ realpath -E /tmp/regfile/ realpath: /tmp/regfile/: Not a directory</pre> Although the behavior of the <i>realpath</i> utility is specified by reference to the <i>realpath</i>() function, which is part of the XSI option, non-XSI implementations that do not support <i>realpath</i>() are nevertheless required to implement <i>realpath</i> in accordance with the requirements described in this standard for <i>realpath</i>().</blockquote> <b>FUTURE DIRECTIONS</b><blockquote>None.</blockquote> <b>SEE ALSO</b><blockquote>ln, ls, pwd, readlink XBD Chapter 8, Section 12.2 XSH Section 2.3, realpath()</blockquote> <b>CHANGE HISTORY</b><blockquote>First released in Issue 8.</blockquote> On page 2901 line 95844 section ln, add readlink and realpath to SEE ALSO. On page 2932 line 96992 section ls, add readlink to SEE ALSO. Issue History Date Modified Username Field Change ====================================================================== 2021-03-09 21:21 steffen New Issue 2021-03-09 21:21 steffen Status New => Under Review 2021-03-09 21:21 steffen Assigned To => ajosey 2021-03-09 21:21 steffen Name => Steffen Nurpmeso 2021-03-09 21:21 steffen Section => Vol. 3: Shell and Utilities. 2021-03-09 21:21 steffen Page Number => (page or range of pages) 2021-03-09 21:21 steffen Line Number => (Line or range of lines) 2021-03-10 04:11 emaste Issue Monitored: emaste 2022-02-22 15:58 geoffclare Note Added: 0005700 2022-02-22 16:01 geoffclare Note Edited: 0005700 2022-02-22 16:09 geoffclare Note Edited: 0005700 2022-02-22 16:11 geoffclare Project 1003.1(2008)/Issue 7 => 1003.1(2016/18)/Issue7+TC2 2022-02-22 16:13 geoffclare Note Edited: 0005700 2022-02-22 21:39 emaste Note Added: 0005701 2022-02-22 21:41 emaste Note Deleted: 0005701 2022-02-22 22:19 steffen Note Added: 0005702 2022-02-22 22:34 calestyo Issue Monitored: calestyo 2022-02-23 08:32 geoffclare Note Added: 0005703 2022-02-23 13:31 emaste Note Added: 0005704 2022-02-23 13:38 calestyo Note Added: 0005705 2022-02-24 09:28 geoffclare Note Added: 0005706 2022-02-24 09:32 geoffclare Note Edited: 0005700 2022-02-24 09:34 geoffclare Note Edited: 0005700 2022-02-24 09:36 geoffclare Note Edited: 0005703 2022-02-25 21:24 mirabilos Note Added: 0005721 2022-07-21 10:41 geoffclare Note Added: 0005898 ======================================================================
