418 lines
13 KiB
HTML
418 lines
13 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>pathchk</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="pathchk"></a> <a name="tag_04_99"></a><!-- pathchk -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_04_99_01"></a>NAME</h4>
|
|
|
|
<blockquote>pathchk - check pathnames</blockquote>
|
|
|
|
<h4><a name="tag_04_99_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>pathchk</tt> <b>[</b><tt>-p</tt><b>]</b> <i>pathname</i><tt>...</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>pathchk</i> utility shall check that one or more pathnames are valid (that is, they could be used to access or create a
|
|
file without causing syntax errors) and portable (that is, no filename truncation results). More extensive portability checks are
|
|
provided by the <b>-p</b> option.</p>
|
|
|
|
<p>By default, the <i>pathchk</i> utility shall check each component of each <i>pathname</i> operand based on the underlying file
|
|
system. A diagnostic shall be written for each <i>pathname</i> operand that:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Is longer than {PATH_MAX} bytes (see <b>Pathname Variable Values</b> in the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap13.html#tag_13">Chapter 13, Headers</a>, <a href=
|
|
"../basedefs/limits.h.html"><i><limits.h></i></a>)</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Contains any component longer than {NAME_MAX} bytes in its containing directory</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Contains any component in a directory that is not searchable</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Contains any character in any component that is not valid in its containing directory</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The format of the diagnostic message is not specified, but shall indicate the error detected and the corresponding
|
|
<i>pathname</i> operand.</p>
|
|
|
|
<p>It shall not be considered an error if one or more components of a <i>pathname</i> operand do not exist as long as a file
|
|
matching the pathname specified by the missing components could be created that does not violate any of the checks specified
|
|
above.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_04"></a>OPTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>pathchk</i> utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/xbd_chap12.html#tag_12_02">Section 12.2, Utility Syntax Guidelines</a>.</p>
|
|
|
|
<p>The following option shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><b>-p</b></dt>
|
|
|
|
<dd>Instead of performing checks based on the underlying file system, write a diagnostic for each <i>pathname</i> operand that:
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Is longer than {_POSIX_PATH_MAX} bytes (see <b>Minimum Values</b> in the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap13.html#tag_13">Chapter 13, Headers</a>, <a href=
|
|
"../basedefs/limits.h.html"><i><limits.h></i></a>)</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Contains any component longer than {_POSIX_NAME_MAX} bytes</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Contains any character in any component that is not in the portable filename character set</p>
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_05"></a>OPERANDS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following operand shall be supported:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>pathname</i></dt>
|
|
|
|
<dd>A pathname to be checked.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_06"></a>STDIN</h4>
|
|
|
|
<blockquote>
|
|
<p>Not used.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_07"></a>INPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_08"></a>ENVIRONMENT VARIABLES</h4>
|
|
|
|
<blockquote>
|
|
<p>The following environment variables shall affect the execution of <i>pathchk</i>:</p>
|
|
|
|
<dl compact>
|
|
<dt><i>LANG</i></dt>
|
|
|
|
<dd>Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/xbd_chap08.html#tag_08_02">Section 8.2, Internationalization Variables</a> for
|
|
the precedence of internationalization variables used to determine the values of locale categories.)</dd>
|
|
|
|
<dt><i>LC_ALL</i></dt>
|
|
|
|
<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
|
|
|
|
<dt><i>LC_CTYPE</i></dt>
|
|
|
|
<dd>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).</dd>
|
|
|
|
<dt><i>LC_MESSAGES</i></dt>
|
|
|
|
<dd>Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard
|
|
error.</dd>
|
|
|
|
<dt><i>NLSPATH</i></dt>
|
|
|
|
<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
Determine the location of message catalogs for the processing of <i>LC_MESSAGES .</i> <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_09"></a>ASYNCHRONOUS EVENTS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_10"></a>STDOUT</h4>
|
|
|
|
<blockquote>
|
|
<p>Not used.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_11"></a>STDERR</h4>
|
|
|
|
<blockquote>
|
|
<p>The standard error shall be used only for diagnostic messages.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_12"></a>OUTPUT FILES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_13"></a>EXTENDED DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_14"></a>EXIT STATUS</h4>
|
|
|
|
<blockquote>
|
|
<p>The following exit values shall be returned:</p>
|
|
|
|
<dl compact>
|
|
<dt> 0</dt>
|
|
|
|
<dd>All <i>pathname</i> operands passed all of the checks.</dd>
|
|
|
|
<dt>>0</dt>
|
|
|
|
<dd>An error occurred.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_15"></a>CONSEQUENCES OF ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>Default.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_04_99_16"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>The <a href="../utilities/test.html"><i>test</i></a> utility can be used to determine whether a given pathname names an existing
|
|
file; it does not, however, give any indication of whether or not any component of the pathname was truncated in a directory where
|
|
the _POSIX_NO_TRUNC feature is not in effect. The <i>pathchk</i> utility does not check for file existence; it performs checks to
|
|
determine whether a pathname does exist or could be created with no pathname component truncation.</p>
|
|
|
|
<p>The <i>noclobber</i> option in the shell (see the <a href="set.html#tag_04_127"><i>set</i></a> special built-in) can be used to
|
|
atomically create a file. As with all file creation semantics in the System Interfaces volume of IEEE Std 1003.1-2001, it
|
|
guarantees atomic creation, but still depends on applications to agree on conventions and cooperate on the use of files after they
|
|
have been created.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_17"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>To verify that all pathnames in an imported data interchange archive are legitimate and unambiguous on the current system:</p>
|
|
|
|
<pre>
|
|
<tt>pax -f archive | sed -e '/ == .*/s///' | xargs pathchk
|
|
if [ $? -eq 0 ]
|
|
then
|
|
pax -r -f archive
|
|
else
|
|
echo Investigate problems before importing files.
|
|
exit 1
|
|
fi
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>To verify that all files in the current directory hierarchy could be moved to any system conforming to the System Interfaces
|
|
volume of IEEE Std 1003.1-2001 that also supports the <a href="../utilities/pax.html"><i>pax</i></a> utility:</p>
|
|
|
|
<pre>
|
|
<tt>find . -print | xargs pathchk -p
|
|
if [ $? -eq 0 ]
|
|
then
|
|
pax -w -f archive .
|
|
else
|
|
echo Portable archive cannot be created.
|
|
exit 1
|
|
fi
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>To verify that a user-supplied pathname names a readable file and that the application can create a file extending the given
|
|
path without truncation and without overwriting any existing file:</p>
|
|
|
|
<pre>
|
|
<tt>case $- in
|
|
*C*) reset="";;
|
|
*) reset="set +C"
|
|
set -C;;
|
|
esac
|
|
test -r "$path" && pathchk "$path.out" &&
|
|
rm "$path.out" > "$path.out"
|
|
if [ $? -ne 0 ]; then
|
|
printf "%s: %s not found or %s.out fails \
|
|
creation checks.\n" $0 "$path" "$path"
|
|
$reset # Reset the noclobber option in case a trap
|
|
# on EXIT depends on it.
|
|
exit 1
|
|
fi
|
|
$reset
|
|
PROCESSING < "$path" > "$path.out"
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The following assumptions are made in this example:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p><b>PROCESSING</b> represents the code that is used by the application to use <b>$path</b> once it is verified that
|
|
<b>$path.out</b> works as intended.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The state of the <i>noclobber</i> option is unknown when this code is invoked and should be set on exit to the state it was in
|
|
when this code was invoked. (The <b>reset</b> variable is used in this example to restore the initial state.)</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Note the usage of:</p>
|
|
|
|
<pre>
|
|
<tt>rm "$path.out" > "$path.out"
|
|
</tt>
|
|
</pre>
|
|
|
|
<ol type="a">
|
|
<li>
|
|
<p>The <i>pathchk</i> command has already verified, at this point, that <b>$path.out</b> is not truncated.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>With the <i>noclobber</i> option set, the shell verifies that <b>$path.out</b> does not already exist before invoking <a href=
|
|
"../utilities/rm.html"><i>rm</i></a>.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the shell succeeded in creating <b>$path.out</b>, <a href="../utilities/rm.html"><i>rm</i></a> removes it so that the
|
|
application can create the file again in the <b>PROCESSING</b> step.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the <b>PROCESSING</b> step wants the file to exist already when it is invoked, the:</p>
|
|
|
|
<pre>
|
|
<tt>rm "$path.out" > "$path.out"
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>should be replaced with:</p>
|
|
|
|
<pre>
|
|
<tt>> "$path.out"
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>which verifies that the file did not already exist, but leaves <b>$path.out</b> in place for use by <b>PROCESSING</b>.</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
</ol>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_18"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>pathchk</i> utility was new for the ISO POSIX-2:1993 standard. It, along with the <a href=
|
|
"../utilities/set.html"><i>set</i></a> <b>-C</b>( <i>noclobber</i>) option added to the shell, replaces the
|
|
<i>mktemp</i>, <i>validfnam</i>, and <i>create</i> utilities that appeared in early proposals. All of these utilities were attempts
|
|
to solve several common problems:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Verify the validity (for several different definitions of "valid") of a pathname supplied by a user, generated by an
|
|
application, or imported from an external source.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Atomically create a file.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Perform various string handling functions to generate a temporary filename.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The <i>create</i> utility, included in an early proposal, provided checking and atomic creation in a single invocation of the
|
|
utility; these are orthogonal issues and need not be grouped into a single utility. Note that the <i>noclobber</i> option also
|
|
provides a way of creating a lock for process synchronization; since it provides an atomic <i>create</i>, there is no race between
|
|
a test for existence and the following creation if it did not exist.</p>
|
|
|
|
<p>Having a function like <a href="../functions/tmpnam.html"><i>tmpnam</i>()</a> in the ISO C standard is important in many
|
|
high-level languages. The shell programming language, however, has built-in string manipulation facilities, making it very easy to
|
|
construct temporary filenames. The names needed obviously depend on the application, but are frequently of a form similar to:</p>
|
|
|
|
<pre>
|
|
<b>$TMPDIR/</b><i>application_abbreviation</i><b>$$.</b><i>suffix</i>
|
|
</pre>
|
|
|
|
<p>In cases where there is likely to be contention for a given suffix, a simple shell <b>for</b> or <b>while</b> loop can be used
|
|
with the shell <i>noclobber</i> option to create a file without risk of collisions, as long as applications trying to use the same
|
|
filename name space are cooperating on the use of files after they have been created.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_19"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_20"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="xcu_chap02.html#tag_02_07"><i>Redirection</i></a> , <a href="set.html#tag_04_127"><i>set</i></a> , <a href=
|
|
"test.html"><i>test</i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_04_99_21"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 4.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|