1PATHCHK(1P)                POSIX Programmer's Manual               PATHCHK(1P)
2
3
4

PROLOG

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
11

NAME

13       pathchk — check pathnames
14

SYNOPSIS

16       pathchk [−p] [−P] pathname...
17

DESCRIPTION

19       The pathchk utility shall check that one or more  pathnames  are  valid
20       (that is, they could be used to access or create a file without causing
21       syntax errors) and portable (that is, no filename truncation  results).
22       More  extensive  portability  checks  are  provided  by  the  −p and −P
23       options.
24
25       By default, the pathchk utility shall  check  each  component  of  each
26       pathname  operand  based  on  the  underlying file system. A diagnostic
27       shall be written for each pathname operand that:
28
29        *  Is longer than {PATH_MAX} bytes (see Pathname  Variable  Values  in
30           the Base Definitions volume of POSIX.1‐2008, <limits.h>)
31
32        *  Contains any component longer than {NAME_MAX} bytes in its contain‐
33           ing directory
34
35        *  Contains any component in a directory that is not searchable
36
37        *  Contains any byte sequence that is  not  valid  in  its  containing
38           directory
39
40       The  format of the diagnostic message is not specified, but shall indi‐
41       cate the error detected and the corresponding pathname operand.
42
43       It shall not be considered an error if one  or  more  components  of  a
44       pathname  operand  do not exist as long as a file matching the pathname
45       specified by the missing components could be created that does not vio‐
46       late any of the checks specified above.
47

OPTIONS

49       The  pathchk  utility  shall  conform to the Base Definitions volume of
50       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
51
52       The following option shall be supported:
53
54       −p        Instead of performing checks based  on  the  underlying  file
55                 system, write a diagnostic for each pathname operand that:
56
57                  *  Is  longer than {_POSIX_PATH_MAX} bytes (see Minimum Val‐
58                     ues in the Base Definitions volume of POSIX.1‐2008, <lim‐
59                     its.h>)
60
61                  *  Contains  any  component  longer  than  {_POSIX_NAME_MAX}
62                     bytes
63
64                  *  Contains any character in any component that  is  not  in
65                     the portable filename character set
66
67       −P        Write a diagnostic for each pathname operand that:
68
69                  *  Contains   a  component  whose  first  character  is  the
70                     <hyphen> character
71
72                  *  Is empty
73

OPERANDS

75       The following operand shall be supported:
76
77       pathname  A pathname to be checked.
78

STDIN

80       Not used.
81

INPUT FILES

83       None.
84

ENVIRONMENT VARIABLES

86       The following environment  variables  shall  affect  the  execution  of
87       pathchk:
88
89       LANG      Provide  a  default  value for the internationalization vari‐
90                 ables that are unset or null. (See the Base Definitions  vol‐
91                 ume  of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
92                 ables the precedence of internationalization  variables  used
93                 to determine the values of locale categories.)
94
95       LC_ALL    If  set  to  a non-empty string value, override the values of
96                 all the other internationalization variables.
97
98       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
99                 bytes of text data as characters (for example, single-byte as
100                 opposed to multi-byte characters in arguments).
101
102       LC_MESSAGES
103                 Determine the locale that should be used to affect the format
104                 and  contents  of  diagnostic  messages  written  to standard
105                 error.
106
107       NLSPATH   Determine the location of message catalogs for the processing
108                 of LC_MESSAGES.
109

ASYNCHRONOUS EVENTS

111       Default.
112

STDOUT

114       Not used.
115

STDERR

117       The standard error shall be used only for diagnostic messages.
118

OUTPUT FILES

120       None.
121

EXTENDED DESCRIPTION

123       None.
124

EXIT STATUS

126       The following exit values shall be returned:
127
128        0    All pathname operands passed all of the checks.
129
130       >0    An error occurred.
131

CONSEQUENCES OF ERRORS

133       Default.
134
135       The following sections are informative.
136

APPLICATION USAGE

138       The  test  utility  can  be  used to determine whether a given pathname
139       names an existing file; it does not, however, give  any  indication  of
140       whether  or not any component of the pathname was truncated in a direc‐
141       tory where the _POSIX_NO_TRUNC feature is not in  effect.  The  pathchk
142       utility does not check for file existence; it performs checks to deter‐
143       mine whether a pathname does exist or could be created with no pathname
144       component truncation.
145
146       The noclobber option in the shell (see the set special built-in) can be
147       used to atomically create a file. As with all file  creation  semantics
148       in  the  System Interfaces volume of POSIX.1‐2008, it guarantees atomic
149       creation, but still depends on applications to agree on conventions and
150       cooperate on the use of files after they have been created.
151
152       To  verify that a pathname meets the requirements of filename portabil‐
153       ity, applications should use both the −p and −P options together.
154

EXAMPLES

156       To verify that all pathnames in an imported  data  interchange  archive
157       are legitimate and unambiguous on the current system:
158
159           # 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
170       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‐2008 that also supports the pax utility:
173
174           find . −exec pathchk −p −P {} +
175           if [ $? −eq 0 ]
176           then
177               pax −w −f ../archive .
178           else
179               echo Portable archive cannot be created.
180               exit 1
181           fi
182
183       To  verify that a user-supplied pathname names a readable file and that
184       the application can create a file  extending  the  given  path  without
185       truncation and without overwriting any existing file:
186
187           case $− in
188               *C*)    reset="";;
189               *)      reset="set +C"
190                       set −C;;
191           esac
192           test −r "$path" && pathchk "$path.out" &&
193               rm "$path.out" > "$path.out"
194           if [ $? −ne 0 ]; then
195               printf "%s: %s not found or %s.out fails \
196           creation checks.\n" $0 "$path$path"
197               $reset    # Reset the noclobber option in case a trap
198                         # on EXIT depends on it.
199               exit 1
200           fi
201           $reset
202           PROCESSING < "$path" > "$path.out"
203
204       The following assumptions are made in this example:
205
206        1. PROCESSING  represents  the code that is used by the application to
207           use $path once it is verified that $path.out works as intended.
208
209        2. The state of the noclobber option is  unknown  when  this  code  is
210           invoked  and should be set on exit to the state it was in when this
211           code was invoked. (The reset variable is used in  this  example  to
212           restore the initial state.)
213
214        3. Note the usage of:
215
216               rm "$path.out" > "$path.out"
217
218            a. The  pathchk  command has already verified, at this point, that
219               $path.out is not truncated.
220
221            b. With  the  noclobber  option  set,  the  shell  verifies   that
222               $path.out does not already exist before invoking rm.
223
224            c. If  the shell succeeded in creating $path.out, rm removes it so
225               that the application can create the file again in the  PROCESS‐
226               ING step.
227
228            d. If  the PROCESSING step wants the file to exist already when it
229               is invoked, the:
230
231                   rm "$path.out" > "$path.out"
232
233               should be replaced with:
234
235                   > "$path.out"
236
237               which verifies that the file did not already exist, but  leaves
238               $path.out in place for use by PROCESSING.
239

RATIONALE

241       The  pathchk  utility  was  new  for the ISO POSIX‐2:1993 standard. It,
242       along with the set −C(noclobber) option added to  the  shell,  replaces
243       the mktemp, validfnam, and create utilities that appeared in early pro‐
244       posals. All of these utilities were attempts to  solve  several  common
245       problems:
246
247        *  Verify   the   validity   (for  several  different  definitions  of
248           ``valid'') of a pathname supplied by a user, generated by an appli‐
249           cation, or imported from an external source.
250
251        *  Atomically create a file.
252
253        *  Perform  various  string handling functions to generate a temporary
254           filename.
255
256       The create utility, included in an early  proposal,  provided  checking
257       and  atomic  creation  in a single invocation of the utility; these are
258       orthogonal issues and need not be grouped into a single  utility.  Note
259       that  the  noclobber  option also provides a way of creating a lock for
260       process synchronization; since it provides an atomic create,  there  is
261       no  race  between a test for existence and the following creation if it
262       did not exist.
263
264       Having a function like tmpnam() in the ISO C standard is  important  in
265       many high-level languages. The shell programming language, however, has
266       built-in string manipulation facilities, making it very  easy  to  con‐
267       struct  temporary  filenames.  The names needed obviously depend on the
268       application, but are frequently of a form similar to:
269
270           $TMPDIR/application_abbreviation$$.suffix
271
272       In cases where there is likely to be contention for a given  suffix,  a
273       simple  shell  for  or  while loop can be used with the shell noclobber
274       option to create a file without risk of collisions, as long as applica‐
275       tions trying to use the same filename name space are cooperating on the
276       use of files after they have been created.
277
278       For historical purposes, −p does not check for the use of the  <hyphen>
279       character as the first character in a component of the pathname, or for
280       an empty pathname operand.
281

FUTURE DIRECTIONS

283       None.
284

SEE ALSO

286       Section 2.7, Redirection, set, test
287
288       The Base Definitions volume of  POSIX.1‐2008,  Chapter  8,  Environment
289       Variables, Section 12.2, Utility Syntax Guidelines, <limits.h>
290
292       Portions  of  this text are reprinted and reproduced in electronic form
293       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
294       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
295       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
296       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
297       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
298       event of any discrepancy between this version and the original IEEE and
299       The Open Group Standard, the original IEEE and The Open Group  Standard
300       is  the  referee document. The original Standard can be obtained online
301       at http://www.unix.org/online.html .
302
303       Any typographical or formatting errors that appear  in  this  page  are
304       most likely to have been introduced during the conversion of the source
305       files to man page format. To report such errors,  see  https://www.ker
306       nel.org/doc/man-pages/reporting_bugs.html .
307
308
309
310IEEE/The Open Group                  2013                          PATHCHK(1P)
Impressum