usr/src/man/man1/ckpath.1

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH CKPATH 1 "Nov 4, 2005"
   7 .SH NAME
   8 ckpath, errpath, helppath, valpath \- display a prompt; verify and return a
   9 pathname
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBckpath\fR [\fB-Q\fR] [\fB-W\fR \fIwidth\fR] [\fB-a\fR | l] [\fB-b\fR | c | f | y]
  14      [\fB-n\fR [o | z]] [\fB-rtwx\fR] [\fB-d\fR \fIdefault\fR] [\fB-h\fR \fIhelp\fR]
  15      [\fB-e\fR \fIerror\fR] [\fB-p\fR \fIprompt\fR] [\fB-k\fR \fIpid\fR [\fB-s\fR \fIsignal\fR]]
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fB/usr/sadm/bin/errpath\fR [\fB-W\fR \fIwidth\fR] [\fB-a\fR | l] [\fB-b\fR | c | f | y]
  21      [\fB-n\fR [o | z]] [\fB-rtwx\fR] [\fB-e\fR \fIerror\fR]
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fB/usr/sadm/bin/helppath\fR [\fB-W\fR \fIwidth\fR] [\fB-a\fR | l] [\fB-b\fR | c | f | y]
  27      [\fB-n\fR [o | z]] [\fB-rtwx\fR] [\fB-h\fR \fIhelp\fR]
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fB/usr/sadm/bin/valpath\fR [\fB-a\fR | l] [\fB-b\fR | c | f | y]
  33      [\fB-n\fR [o | z]] [\fB-rtwx\fR] \fIinput\fR
  34 .fi
  35
  36 .SH DESCRIPTION
  37 .sp
  38 .LP
  39 The \fBckpath\fR utility prompts a user and validates the response. It defines,
  40 among other things, a prompt message whose response should be a pathname, text
  41 for help and error messages, and a default value (which is returned if the user
  42 responds with a RETURN).
  43 .sp
  44 .LP
  45 The pathname must obey the criteria specified by the first group of options. If
  46 no criteria is defined, the pathname must be for a normal file that does not
  47 yet exist. If neither \fB-a\fR (absolute) or \fB-l\fR (relative) is given, then
  48 either is assumed to be valid.
  49 .sp
  50 .LP
  51 All messages are limited in length to 79 characters and are formatted
  52 automatically. Tabs and newlines are removed after a single white space
  53 character in a message definition, but spaces are not removed. When a tilde is
  54 placed at the beginning or end of a message definition, the default text is
  55 inserted at that point, allowing both custom text and the default text to be
  56 displayed.
  57 .sp
  58 .LP
  59 If the prompt, help or error message is not defined, the default message (as
  60 defined under EXAMPLES) is displayed.
  61 .sp
  62 .LP
  63 Three visual tool modules are linked to the \fBckpath\fR command. They are
  64 \fBerrpath\fR (which formats and displays an error message on the standard
  65 output), \fBhelppath\fR (which formats and displays a help message on the
  66 standard output), and \fBvalpath\fR (which validates a response).
  67 .SH OPTIONS
  68 .sp
  69 .LP
  70 The following options are supported:
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fB-a\fR\fR
  75 .ad
  76 .RS 14n
  77 Pathname must be an absolute path.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fB-b\fR\fR
  84 .ad
  85 .RS 14n
  86 Pathname must be a block special file.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fB-c\fR\fR
  93 .ad
  94 .RS 14n
  95 Pathname must be a character special file.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fB-d\fR \fIdefault\fR\fR
 102 .ad
 103 .RS 14n
 104 Defines the default value as \fIdefault\fR. The default is not validated and so
 105 does not have to meet any criteria.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fB-e\fR \fIerror\fR\fR
 112 .ad
 113 .RS 14n
 114 Defines the error message as \fI error\fR.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fB-f\fR\fR
 121 .ad
 122 .RS 14n
 123 Pathname must be a regular file.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fB-h\fR \fIhelp\fR\fR
 130 .ad
 131 .RS 14n
 132 Defines the help message as \fI help\fR.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fB-k\fR \fIpid\fR\fR
 139 .ad
 140 .RS 14n
 141 Specifies that process \fBID\fR \fIpid\fR is to be sent a signal if the user
 142 chooses to quit.
 143 .RE
 144
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fB-l\fR\fR
 149 .ad
 150 .RS 14n
 151 Pathname must be a relative path.
 152 .RE
 153
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fB-n\fR\fR
 158 .ad
 159 .RS 14n
 160 Pathname must not exist (must be new).
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fB-o\fR\fR
 167 .ad
 168 .RS 14n
 169 Pathname must exist (must be old).
 170 .RE
 171
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fB-p\fR \fIprompt\fR\fR
 176 .ad
 177 .RS 14n
 178 Defines the prompt message as \fIprompt\fR.
 179 .RE
 180
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fB-Q\fR\fR
 185 .ad
 186 .RS 14n
 187 Specifies that \fBquit\fR is not allowed as a valid response.
 188 .RE
 189
 190 .sp
 191 .ne 2
 192 .na
 193 \fB\fB-r\fR\fR
 194 .ad
 195 .RS 14n
 196 Pathname must be readable.
 197 .RE
 198
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fB-s\fR \fIsignal\fR\fR
 203 .ad
 204 .RS 14n
 205 Specifies that the process \fBID\fR \fIpid\fR defined with the \fB-k\fR option
 206 is to be sent signal \fIsignal\fR when quit is chosen. If no signal is
 207 specified, \fBSIGTERM\fR is used.
 208 .RE
 209
 210 .sp
 211 .ne 2
 212 .na
 213 \fB\fB-t\fR\fR
 214 .ad
 215 .RS 14n
 216 Pathname must be creatable (touchable). Pathname will be created if it does not
 217 already exist.
 218 .RE
 219
 220 .sp
 221 .ne 2
 222 .na
 223 \fB\fB-w\fR\fR
 224 .ad
 225 .RS 14n
 226 Pathname must be writable.
 227 .RE
 228
 229 .sp
 230 .ne 2
 231 .na
 232 \fB\fB-W\fR \fIwidth\fR\fR
 233 .ad
 234 .RS 14n
 235 Specify that prompt, help and error messages be formatted to a line length of
 236 \fIwidth\fR.
 237 .RE
 238
 239 .sp
 240 .ne 2
 241 .na
 242 \fB\fB-x\fR\fR
 243 .ad
 244 .RS 14n
 245 Pathname must be executable.
 246 .RE
 247
 248 .sp
 249 .ne 2
 250 .na
 251 \fB\fB-y\fR\fR
 252 .ad
 253 .RS 14n
 254 Pathname must be a directory.
 255 .RE
 256
 257 .sp
 258 .ne 2
 259 .na
 260 \fB\fB-z\fR\fR
 261 .ad
 262 .RS 14n
 263 Pathname must have a file having a size greater than zero bytes.
 264 .RE
 265
 266 .SH OPERANDS
 267 .sp
 268 .LP
 269 The following operand is supported:
 270 .sp
 271 .ne 2
 272 .na
 273 \fB\fIinput\fR\fR
 274 .ad
 275 .RS 9n
 276 Input to be verified against validation options.
 277 .RE
 278
 279 .SH EXAMPLES
 280 .sp
 281 .LP
 282 The text of the default messages for \fBckpath\fR depends upon  the criteria
 283 options that have been used.
 284 .LP
 285 \fBExample 1 \fRDefault prompt
 286 .sp
 287 .LP
 288 An example default prompt for \fBckpath\fR (using the \fB-a\fR option) is:
 289
 290 .sp
 291 .in +2
 292 .nf
 293 example% \fBckpath \fR\fB-a\fR
 294 Enter an absolute pathname [?,q]
 295 .fi
 296 .in -2
 297 .sp
 298
 299 .LP
 300 \fBExample 2 \fRDefault error message
 301 .sp
 302 .LP
 303 An example default error message (using the \fB-a\fR option) is:
 304
 305 .sp
 306 .in +2
 307 .nf
 308 example% \fB/usr/sadm/bin/errpath \fR\fB-a\fR
 309 ERROR: A pathname is a filename, optionally preceded by parent
 310        directories.
 311        The pathname you enter: - must begin with a slash (/)
 312 .fi
 313 .in -2
 314 .sp
 315
 316 .LP
 317 \fBExample 3 \fRDefault help message
 318 .sp
 319 .LP
 320 An example default help message (using the \fB-a\fR option) is:
 321
 322 .sp
 323 .in +2
 324 .nf
 325 example% \fB/usr/sadm/bin/helppath \fR\fB-a\fR
 326 A pathname is a filename, optionally preceded by parent directories.
 327 The pathname you enter: - must begin with a slash (/)
 328 .fi
 329 .in -2
 330 .sp
 331
 332 .LP
 333 \fBExample 4 \fRThe quit option
 334 .sp
 335 .LP
 336 When the quit option is chosen (and allowed), \fBq\fR is returned along with
 337 the return code \fB3\fR. Quit input gets a trailing newline.
 338
 339 .LP
 340 \fBExample 5 \fRUsing the valpath module
 341 .sp
 342 .LP
 343 The \fBvalpath\fR module will produce a usage message on stderr. It returns
 344 \fB0\fR for success and non-zero for failure.
 345
 346 .sp
 347 .in +2
 348 .nf
 349 example% \fB/usr/sadm/bin/valpath\fR
 350 usage: valpath [\fB-[a|l][b|c|f|y][n|[o|z]]rtwx\fR] input
 351     .
 352     .
 353     .
 354 .fi
 355 .in -2
 356 .sp
 357
 358 .SH EXIT STATUS
 359 .sp
 360 .LP
 361 The following exit values are returned:
 362 .sp
 363 .ne 2
 364 .na
 365 \fB\fB0\fR\fR
 366 .ad
 367 .RS 5n
 368 Successful execution.
 369 .RE
 370
 371 .sp
 372 .ne 2
 373 .na
 374 \fB\fB1\fR\fR
 375 .ad
 376 .RS 5n
 377 \fBEOF\fR on input, or negative width on \fB-W\fR option, or usage error.
 378 .RE
 379
 380 .sp
 381 .ne 2
 382 .na
 383 \fB\fB2\fR\fR
 384 .ad
 385 .RS 5n
 386 Mutually exclusive options.
 387 .RE
 388
 389 .sp
 390 .ne 2
 391 .na
 392 \fB\fB3\fR\fR
 393 .ad
 394 .RS 5n
 395 User termination (quit).
 396 .RE
 397
 398 .sp
 399 .ne 2
 400 .na
 401 \fB\fB4\fR\fR
 402 .ad
 403 .RS 5n
 404 Mutually exclusive options.
 405 .RE
 406
 407 .SH SEE ALSO
 408 .sp
 409 .LP
 410 \fBsignal.h\fR(3HEAD), \fBattributes\fR(5)