share/man/man1/pathchk.1

   1 '\" te
   2 .\"  Copyright (c) 1992, X/Open Company Limited  All Rights Reserved  Portions Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   4 .\" http://www.opengroup.org/bookstore/.
   5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   6 .\"  This notice shall appear on any product containing this material.
   7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  10 .TH PATHCHK 1 "Feb 1, 1995"
  11 .SH NAME
  12 pathchk \- check path names
  13 .SH SYNOPSIS
  14 .LP
  15 .nf
  16 \fBpathchk\fR [\fB-p\fR] \fIpath\fR...
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The \fBpathchk\fR command will check that one or more path names are valid
  23 (that is, they could be used to access or create a file without causing syntax
  24 errors) and portable (that is, no filename truncation will result). More
  25 extensive portability checks are provided by the \fB-p\fR option.
  26 .sp
  27 .LP
  28 By default, \fBpathchk\fR will check each component of each \fIpath\fR operand
  29 based on the underlying file system. A diagnostic will be written for each
  30 \fIpath\fR operand that:
  31 .RS +4
  32 .TP
  33 .ie t \(bu
  34 .el o
  35 is longer than \fIPATH_MAX\fR bytes.
  36 .RE
  37 .RS +4
  38 .TP
  39 .ie t \(bu
  40 .el o
  41 contains any component longer than \fINAME_MAX\fR bytes in its containing
  42 directory
  43 .RE
  44 .RS +4
  45 .TP
  46 .ie t \(bu
  47 .el o
  48 contains any component in a directory that is not searchable
  49 .RE
  50 .RS +4
  51 .TP
  52 .ie t \(bu
  53 .el o
  54 contains any character in any component that is not valid in its containing
  55 directory.
  56 .RE
  57 .sp
  58 .LP
  59 The format of the diagnostic message is not specified, but will indicate the
  60 error detected and the corresponding \fIpath\fR operand.
  61 .sp
  62 .LP
  63 It will not be considered an error if one or more components of a \fIpath\fR
  64 operand do not exist as long as a file matching the path name specified by the
  65 missing components could be created that does not violate any of the checks
  66 specified above.
  67 .SH OPTIONS
  68 .sp
  69 .LP
  70 The following option is supported:
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fB-p\fR\fR
  75 .ad
  76 .RS 6n
  77 Instead of performing checks based on the underlying file system, write a
  78 diagnostic for each \fIpath\fR operand that:
  79 .RS +4
  80 .TP
  81 .ie t \(bu
  82 .el o
  83 is longer than \fB_POSIX_PATH_MAX \fR bytes
  84 .RE
  85 .RS +4
  86 .TP
  87 .ie t \(bu
  88 .el o
  89 contains any component longer than \fB_POSIX_NAME_MAX\fR bytes
  90 .RE
  91 .RS +4
  92 .TP
  93 .ie t \(bu
  94 .el o
  95 contains any character in any component that is not in the portable filename
  96 character set.
  97 .RE
  98 .RE
  99
 100 .SH OPERANDS
 101 .sp
 102 .LP
 103 The following operand is supported:
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fIpath\fR\fR
 108 .ad
 109 .RS 8n
 110 A path to be checked.
 111 .RE
 112
 113 .SH USAGE
 114 .sp
 115 .LP
 116 See \fBlargefile\fR(5) for the description of the behavior of \fBpathchk\fR
 117 when encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
 118 .SH EXAMPLES
 119 .LP
 120 \fBExample 1 \fRUsing the pathchk command
 121 .sp
 122 .LP
 123 To verify that all paths in an imported data interchange archive are legitimate
 124 and unambiguous on the current system:
 125
 126 .sp
 127 .in +2
 128 .nf
 129 example% \fBpax -f archive | sed -e '/ == .*/s///' | xargs pathchk
 130 if [ $? -eq 0 ]
 131 then
 132         pax -r -f archive
 133 else
 134         echo Investigate problems before importing files.
 135         exit 1
 136 fi\fR
 137 .fi
 138 .in -2
 139 .sp
 140
 141 .sp
 142 .LP
 143 To verify that all files in the current directory hierarchy could be moved to
 144 any system conforming to the X/Open specification that also  supports the
 145 \fBpax\fR(1) command:
 146
 147 .sp
 148 .in +2
 149 .nf
 150 example% \fBfind . -print | xargs pathchk -p
 151 if [ $? \(mieq 0 ]
 152 then
 153         pax -w -f archive .
 154 else
 155         echo Portable archive cannot be created.
 156         exit 1
 157 fi\fR
 158 .fi
 159 .in -2
 160 .sp
 161
 162 .sp
 163 .LP
 164 To verify that a user-supplied path names a readable file and that the
 165 application can create a file extending the given path without truncation and
 166 without overwriting any existing file:
 167
 168 .sp
 169 .in +2
 170 .nf
 171 example% \fBcase $- in
 172         *C*)    reset="";;
 173         *)      reset="set +C"
 174                 set -C;;
 175 esac
 176 test -r "$path" && pathchk "$path.out" &&
 177         rm "$path.out" > "$path.out"
 178 if [ $? -ne 0 ]; then
 179         printf "%s: %s not found or %s.out fails \e
 180 creation checks.\en" $0 "$path" "$path"
 181         $reset  # reset the noclobber option in case a trap
 182                 # on EXIT depends on it
 183         exit 1
 184 fi
 185 $reset
 186 PROCESSING < "$path" > "$path.out"\fR
 187 .fi
 188 .in -2
 189 .sp
 190
 191 .sp
 192 .LP
 193 The following assumptions are made in this example:
 194
 195 .RS +4
 196 .TP
 197 1.
 198 \fBPROCESSING\fR represents the code that will be used by the application to
 199 use \fB$path\fR once it is verified that \fB$path.out\fR will work as intended.
 200 .RE
 201 .RS +4
 202 .TP
 203 2.
 204 The state of the \fBnoclobber\fR option is unknown when this code is invoked
 205 and should be set on exit to the state it was in when this code was invoked.
 206 (The \fBreset\fR variable is used in this example to restore the initial
 207 state.)
 208 .RE
 209 .RS +4
 210 .TP
 211 3.
 212 Note the usage of:
 213 .sp
 214 .in +2
 215 .nf
 216 \fBrm "$path.out" > "$path.out"\fR
 217 .fi
 218 .in -2
 219 .sp
 220
 221 .sp
 222 .ne 2
 223 .na
 224 \fBa.\fR
 225 .ad
 226 .RS 6n
 227 The \fBpathchk\fR command has already verified, at this point, that
 228 \fB$path.out\fR will not be truncated.
 229 .RE
 230
 231 .sp
 232 .ne 2
 233 .na
 234 \fBb.\fR
 235 .ad
 236 .RS 6n
 237 With the \fBnoclobber\fR option set, the shell will verify that \fB$path.out\fR
 238 does not already exist before invoking \fBrm\fR.
 239 .RE
 240
 241 .sp
 242 .ne 2
 243 .na
 244 \fBc.\fR
 245 .ad
 246 .RS 6n
 247 If the shell succeeded in creating \fB$path.out\fR, \fBrm\fR will remove it so
 248 that the application can create the file again in the \fBPROCESSING\fR step.
 249 .RE
 250
 251 .sp
 252 .ne 2
 253 .na
 254 \fBd.\fR
 255 .ad
 256 .RS 6n
 257 If the \fBPROCESSING\fR step wants the file to exist already when it is
 258 invoked, the:
 259 .sp
 260 .in +2
 261 .nf
 262 \fBrm "$path.out" > "$path.out"\fR
 263 .fi
 264 .in -2
 265 .sp
 266
 267 should be replaced with:
 268 .sp
 269 .in +2
 270 .nf
 271 \fB> "$path.out"\fR
 272 .fi
 273 .in -2
 274 .sp
 275
 276 which will verify that the file did not already exist, but leave
 277 \fB$path.out\fR in place for use by \fBPROCESSING\fR.
 278 .RE
 279
 280 .RE
 281 .SH ENVIRONMENT VARIABLES
 282 .sp
 283 .LP
 284 See \fBenviron\fR(5) for descriptions of the following environment variables
 285 that affect the execution of \fBpathchk\fR: \fBLANG\fR, \fBLC_ALL\fR,
 286 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 287 .SH EXIT STATUS
 288 .sp
 289 .LP
 290 The following exit values are returned:
 291 .sp
 292 .ne 2
 293 .na
 294 \fB\fB0\fR\fR
 295 .ad
 296 .RS 6n
 297 All \fIpath\fR operands passed all of the checks.
 298 .RE
 299
 300 .sp
 301 .ne 2
 302 .na
 303 \fB\fB>0\fR\fR
 304 .ad
 305 .RS 6n
 306 An error occurred.
 307 .RE
 308
 309 .SH ATTRIBUTES
 310 .sp
 311 .LP
 312 See \fBattributes\fR(5) for descriptions of the following attributes:
 313 .sp
 314
 315 .sp
 316 .TS
 317 box;
 318 c | c
 319 l | l .
 320 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 321 _
 322 Interface Stability     Standard
 323 .TE
 324
 325 .SH SEE ALSO
 326 .sp
 327 .LP
 328 \fBpax\fR(1), \fBtest\fR(1), \fBattributes\fR(5), \fBenviron\fR(5),
 329 \fBlargefile\fR(5), \fBstandards\fR(5)