1PATHCHK(1P) POSIX Programmer's Manual PATHCHK(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 pathchk — check pathnames
13
15 pathchk [-p] [-P] pathname...
16
18 The pathchk utility shall check that one or more pathnames are valid
19 (that is, they could be used to access or create a file without causing
20 syntax errors) and portable (that is, no filename truncation results).
21 More extensive portability checks are provided by the -p and -P
22 options.
23 By default, the pathchk utility shall check each component of each
25 pathname operand based on the underlying file system. A diagnostic
26 shall be written for each pathname operand that:
27 * Is longer than {PATH_MAX} bytes (see Pathname Variable Values in
29 the Base Definitions volume of POSIX.1‐2017, <limits.h>)
30 * Contains any component longer than {NAME_MAX} bytes in its contain‐
32 ing directory
33 * Contains any component in a directory that is not searchable
35 * Contains any byte sequence that is not valid in its containing
37 directory
38 The format of the diagnostic message is not specified, but shall indi‐
40 cate the error detected and the corresponding pathname operand.
41 It shall not be considered an error if one or more components of a
43 pathname operand do not exist as long as a file matching the pathname
44 specified by the missing components could be created that does not vio‐
45 late any of the checks specified above.
46
48 The pathchk utility shall conform to the Base Definitions volume of
49 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
50 The following option shall be supported:
52 -p Instead of performing checks based on the underlying file
54 system, write a diagnostic for each pathname operand that:
55 * Is longer than {_POSIX_PATH_MAX} bytes (see Minimum Val‐
57 ues in the Base Definitions volume of POSIX.1‐2017, <lim‐
58 its.h>)
59 * Contains any component longer than {_POSIX_NAME_MAX}
61 bytes
62 * Contains any character in any component that is not in
64 the portable filename character set
65 -P Write a diagnostic for each pathname operand that:
67 * Contains a component whose first character is the
69 <hyphen-minus> character
70 * Is empty
72
74 The following operand shall be supported:
75 pathname A pathname to be checked.
77
79 Not used.
80
82 None.
83
85 The following environment variables shall affect the execution of
86 pathchk:
87 LANG Provide a default value for the internationalization vari‐
89 ables that are unset or null. (See the Base Definitions vol‐
90 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
91 ables the precedence of internationalization variables used
92 to determine the values of locale categories.)
93 LC_ALL If set to a non-empty string value, override the values of
95 all the other internationalization variables.
96 LC_CTYPE Determine the locale for the interpretation of sequences of
98 bytes of text data as characters (for example, single-byte as
99 opposed to multi-byte characters in arguments).
100 LC_MESSAGES
102 Determine the locale that should be used to affect the format
103 and contents of diagnostic messages written to standard
104 error.
105 NLSPATH Determine the location of message catalogs for the processing
107 of LC_MESSAGES.
108
110 Default.
111
113 Not used.
114
116 The standard error shall be used only for diagnostic messages.
117
119 None.
120
122 None.
123
125 The following exit values shall be returned:
126 0 All pathname operands passed all of the checks.
128 >0 An error occurred.
130
132 Default.
133 The following sections are informative.
135
137 The test utility can be used to determine whether a given pathname
138 names an existing file; it does not, however, give any indication of
139 whether or not any component of the pathname was truncated in a direc‐
140 tory where the _POSIX_NO_TRUNC feature is not in effect. The pathchk
141 utility does not check for file existence; it performs checks to deter‐
142 mine whether a pathname does exist or could be created with no pathname
143 component truncation.
144 The noclobber option in the shell (see the set special built-in) can be
146 used to atomically create a file. As with all file creation semantics
147 in the System Interfaces volume of POSIX.1‐2017, it guarantees atomic
148 creation, but still depends on applications to agree on conventions and
149 cooperate on the use of files after they have been created.
150 To verify that a pathname meets the requirements of filename portabil‐
152 ity, applications should use both the -p and -P options together.
153
155 To verify that all pathnames in an imported data interchange archive
156 are legitimate and unambiguous on the current system:
157 # This example assumes that no pathnames in the archive
160 # contain <newline> characters.
161 pax -f archive | sed -e 's/[^[:alnum:]]/\\&/g' | xargs pathchk --
162 if [ $? -eq 0 ]
163 then
164 pax -r -f archive
165 else
166 echo Investigate problems before importing files.
167 exit 1
168 fi
169 To verify that all files in the current directory hierarchy could be
171 moved to any system conforming to the System Interfaces volume of
172 POSIX.1‐2017 that also supports the pax utility:
173 find . -exec pathchk -p -P {} +
176 if [ $? -eq 0 ]
177 then
178 pax -w -f ../archive .
179 else
180 echo Portable archive cannot be created.
181 exit 1
182 fi
183 To verify that a user-supplied pathname names a readable file and that
185 the application can create a file extending the given path without
186 truncation and without overwriting any existing file:
187 case $- in
190 *C*) reset="";;
191 *) reset="set +C"
192 set -C;;
193 esac
194 test -r "$path" && pathchk "$path.out" &&
195 rm "$path.out" > "$path.out"
196 if [ $? -ne 0 ]; then
197 printf "%s: %s not found or %s.out fails \
198 creation checks.\n" $0 "$path$path"
199 $reset # Reset the noclobber option in case a trap
200 # on EXIT depends on it.
201 exit 1
202 fi
203 $reset
204 PROCESSING < "$path" > "$path.out"
205 The following assumptions are made in this example:
207 1. PROCESSING represents the code that is used by the application to
209 use $path once it is verified that $path.out works as intended.
210 2. The state of the noclobber option is unknown when this code is
212 invoked and should be set on exit to the state it was in when this
213 code was invoked. (The reset variable is used in this example to
214 restore the initial state.)
215 3. Note the usage of:
217 rm "$path.out" > "$path.out"
220 a. The pathchk command has already verified, at this point, that
222 $path.out is not truncated.
223 b. With the noclobber option set, the shell verifies that
225 $path.out does not already exist before invoking rm.
226 c. If the shell succeeded in creating $path.out, rm removes it so
228 that the application can create the file again in the PROCESS‐
229 ING step.
230 d. If the PROCESSING step wants the file to exist already when it
232 is invoked, the:
233 rm "$path.out" > "$path.out"
236 should be replaced with:
238 > "$path.out"
241 which verifies that the file did not already exist, but leaves
243 $path.out in place for use by PROCESSING.
244
246 The pathchk utility was new for the ISO POSIX‐2:1993 standard. It,
247 along with the set -C(noclobber) option added to the shell, replaces
248 the mktemp, validfnam, and create utilities that appeared in early pro‐
249 posals. All of these utilities were attempts to solve several common
250 problems:
251 * Verify the validity (for several different definitions of
253 ``valid'') of a pathname supplied by a user, generated by an appli‐
254 cation, or imported from an external source.
255 * Atomically create a file.
257 * Perform various string handling functions to generate a temporary
259 filename.
260 The create utility, included in an early proposal, provided checking
262 and atomic creation in a single invocation of the utility; these are
263 orthogonal issues and need not be grouped into a single utility. Note
264 that the noclobber option also provides a way of creating a lock for
265 process synchronization; since it provides an atomic create, there is
266 no race between a test for existence and the following creation if it
267 did not exist.
268 Having a function like tmpnam() in the ISO C standard is important in
270 many high-level languages. The shell programming language, however, has
271 built-in string manipulation facilities, making it very easy to con‐
272 struct temporary filenames. The names needed obviously depend on the
273 application, but are frequently of a form similar to:
274 $TMPDIR/application_abbreviation$$.suffix
277 In cases where there is likely to be contention for a given suffix, a
279 simple shell for or while loop can be used with the shell noclobber
280 option to create a file without risk of collisions, as long as applica‐
281 tions trying to use the same filename name space are cooperating on the
282 use of files after they have been created.
283 For historical purposes, -p does not check for the use of the <hyphen-
285 minus> character as the first character in a component of the pathname,
286 or for an empty pathname operand.
287
289 None.
290
292 Section 2.7, Redirection, set, test
293 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
295 Variables, Section 12.2, Utility Syntax Guidelines, <limits.h>
296
298 Portions of this text are reprinted and reproduced in electronic form
299 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
300 table Operating System Interface (POSIX), The Open Group Base Specifi‐
301 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
302 Electrical and Electronics Engineers, Inc and The Open Group. In the
303 event of any discrepancy between this version and the original IEEE and
304 The Open Group Standard, the original IEEE and The Open Group Standard
305 is the referee document. The original Standard can be obtained online
306 at http://www.opengroup.org/unix/online.html .
307 Any typographical or formatting errors that appear in this page are
309 most likely to have been introduced during the conversion of the source
310 files to man page format. To report such errors, see https://www.ker‐
311 nel.org/doc/man-pages/reporting_bugs.html .
312IEEE/The Open Group 2017 PATHCHK(1P)