usr/src/man/man1/ckrange.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 CKRANGE 1 "Nov 4, 2005"
   7 .SH NAME
   8 ckrange, errange, helprange, valrange \- prompts for and validates an integer
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBckrange\fR [\fB-Q\fR] [\fB-W\fR \fIwidth\fR] [\fB-l\fR \fIlower\fR] [\fB-u\fR \fIupper\fR] [\fB-b\fR \fIbase\fR]
  13      [\fB-d\fR \fIdefault\fR] [\fB-h\fR \fIhelp\fR] [\fB-e\fR \fIerror\fR] [\fB-p\fR \fIprompt\fR]
  14      [\fB-k\fR \fIpid\fR [\fB-s\fR \fIsignal\fR]]
  15 .fi
  16
  17 .LP
  18 .nf
  19 \fB/usr/sadm/bin/errange\fR [\fB-W\fR \fIwidth\fR] [\fB-e\fR \fIerror\fR] [\fB-l\fR \fIlower\fR]
  20      [\fB-u\fR \fIupper\fR] [\fB-b\fR \fIbase\fR]
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fB/usr/sadm/bin/helprange\fR [\fB-W\fR \fIwidth\fR] [\fB-h\fR \fIhelp\fR] [\fB-l\fR \fIlower\fR]
  26      [\fB-u\fR \fIupper\fR] [\fB-b\fR \fIbase\fR]
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fB/usr/sadm/bin/valrange\fR [\fB-l\fR \fIlower\fR] [\fB-u\fR \fIupper\fR] [\fB-b\fR \fIbase\fR] \fIinput\fR
  32 .fi
  33
  34 .SH DESCRIPTION
  35 .sp
  36 .LP
  37 The \fBckrange\fR utility prompts a user for an integer between a specified
  38 range and determines whether this response is valid. It defines, among other
  39 things, a prompt message whose response should be an integer in the range
  40 specified, text for help and error messages, and a default value (which is
  41 returned if the user responds with a RETURN).
  42 .sp
  43 .LP
  44 This command also defines a range for valid input. If either the lower or upper
  45 limit is left undefined, then the range is bounded on only one end.
  46 .sp
  47 .LP
  48 All messages are limited in length to 79 characters and are formatted
  49 automatically. Tabs and newlines are removed after a single whitespace
  50 character in a message definition, but spaces are not removed. When a tilde is
  51 placed at the beginning or end of a message definition, the default text will
  52 be inserted at that point, allowing both custom text and the default text to be
  53 displayed.
  54 .sp
  55 .LP
  56 If the prompt, help or error message is not defined, the default message (as
  57 defined under EXAMPLES) is displayed.
  58 .sp
  59 .LP
  60 Three visual tool modules are linked to the \fBckrange\fR command. They are
  61 \fBerrange\fR (which formats and displays an error message on the standard
  62 output), \fBhelprange\fR (which formats and displays a help message on the
  63 standard output), and \fBvalrange\fR (which validates a response).
  64 .sp
  65 .LP
  66 \fBNote:\fR Negative "input" arguments confuse \fBgetopt\fR in \fBvalrange\fR.
  67 By inserting a "\(mi" before the argument, \fBgetopt\fR processing will stop.
  68 See \fBgetopt\fR(1) and \fBIntro\fR(1) about \fBgetopt\fR parameter handling.
  69 \fBgetopt\fR is used to parse positional parameters and to check for legal
  70 options.
  71 .SH OPTIONS
  72 .sp
  73 .LP
  74 The following options are supported:
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fB-b\fR \fIbase\fR\fR
  79 .ad
  80 .RS 14n
  81 Defines the base for input. Must be 2 to 36, default is 10. Base conversion
  82 uses \fBstrtol\fR(3C). Output is always base 10.
  83 .RE
  84
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fB-d\fR \fIdefault\fR\fR
  89 .ad
  90 .RS 14n
  91 Defines the default value as \fIdefault\fR. \fIdefault\fR is converted using
  92 \fBstrtol\fR(3C) in the desired base. Any characters invalid in the specified
  93 base will terminate the \fBstrtol\fR conversion without error.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fB-e\fR \fIerror\fR\fR
 100 .ad
 101 .RS 14n
 102 Defines the error message as \fI error\fR.
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fB-h\fR \fIhelp\fR\fR
 109 .ad
 110 .RS 14n
 111 Defines the help message as \fI help\fR.
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fB-k\fR \fIpid\fR\fR
 118 .ad
 119 .RS 14n
 120 Specifies that process \fBID\fR \fIpid\fR is to be sent a signal if the user
 121 chooses to quit.
 122 .RE
 123
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fB-l\fR \fIlower\fR\fR
 128 .ad
 129 .RS 14n
 130 Defines the lower limit of the range as \fIlower\fR. Default is the machine's
 131 largest negative long.
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fB-p\fR \fIprompt\fR\fR
 138 .ad
 139 .RS 14n
 140 Defines the prompt message as \fIprompt\fR.
 141 .RE
 142
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fB-Q\fR\fR
 147 .ad
 148 .RS 14n
 149 Specifies that quit will not be allowed as a valid response.
 150 .RE
 151
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fB-s\fR \fIsignal\fR\fR
 156 .ad
 157 .RS 14n
 158 Specifies that the process \fBID\fR \fIpid\fR defined with the \fB-k\fR option
 159 is to be sent signal \fIsignal\fR when quit is chosen. If no signal is
 160 specified,  \fBSIGTERM\fR is used.
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fB-u\fR \fIupper\fR\fR
 167 .ad
 168 .RS 14n
 169 Defines the upper limit of the range as \fIupper\fR. Default is the machine's
 170 largest positive long.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fB-W\fR \fIwidth\fR\fR
 177 .ad
 178 .RS 14n
 179 Specifies that prompt, help and error messages will be formatted to a line
 180 length of \fIwidth\fR.
 181 .RE
 182
 183 .SH OPERANDS
 184 .sp
 185 .LP
 186 The following operand is supported:
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fIinput\fR\fR
 191 .ad
 192 .RS 9n
 193 Input to be verified against upper and lower limits and base.
 194 .RE
 195
 196 .SH EXAMPLES
 197 .LP
 198 \fBExample 1 \fRDefault base 10 prompt
 199 .sp
 200 .LP
 201 The default base 10 prompt for \fBckrange\fR is:
 202
 203 .sp
 204 .in +2
 205 .nf
 206 example% \fBckrange\fR
 207 Enter an integer between \fIlower_bound \fRand
 208 \fIupper_bound \fR[\fIlower_bound\(miupper_bound\fR,?,q]:
 209 .fi
 210 .in -2
 211 .sp
 212
 213 .LP
 214 \fBExample 2 \fRDefault base 10 error message
 215 .sp
 216 .LP
 217 The default base 10 error message is:
 218
 219 .sp
 220 .in +2
 221 .nf
 222 example% \fB/usr/sadm/bin/errange\fR
 223 ERROR: Please enter an integer between \fIlower_bound \e\fR
 224      and \fIupper_bound\fR.
 225 .fi
 226 .in -2
 227 .sp
 228
 229 .LP
 230 \fBExample 3 \fRDefault base 10 help message
 231 .sp
 232 .LP
 233 The default base 10 help message is:
 234
 235 .sp
 236 .in +2
 237 .nf
 238 example% \fB/usr/sadm/bin/helprange\fR
 239 Please enter an integer between \fIlower_bound\fR and \fIupper_bound\fR.
 240 .fi
 241 .in -2
 242 .sp
 243
 244 .LP
 245 \fBExample 4 \fRChanging messages for a base other than 10
 246 .sp
 247 .LP
 248 The messages are changed from ``integer'' to ``base \fIbase\fR integer'' if the
 249 base is set to a number other than 10. For example,
 250
 251 .sp
 252 .in +2
 253 .nf
 254 example% \fB/usr/sadm/bin/helprange -b 36\fR
 255 .fi
 256 .in -2
 257 .sp
 258
 259 .LP
 260 \fBExample 5 \fRUsing the quit option
 261 .sp
 262 .LP
 263 When the quit option is chosen (and allowed), \fBq\fR is returned along with
 264 the return code \fB3\fR. Quit input gets a trailing newline.
 265
 266 .LP
 267 \fBExample 6 \fRUsing the valrange module
 268 .sp
 269 .LP
 270 The \fBvalrange\fR module will produce a usage message on stderr. It returns
 271 \fB0\fR for success and non-zero for failure.
 272
 273 .sp
 274 .in +2
 275 .nf
 276 example% \fB/usr/sadm/bin/valrange\fR
 277 usage: valrange [-l lower] [-u upper] [-b base] input
 278 .fi
 279 .in -2
 280 .sp
 281
 282 .SH EXIT STATUS
 283 .sp
 284 .LP
 285 The following exit values are returned:
 286 .sp
 287 .ne 2
 288 .na
 289 \fB\fB0\fR\fR
 290 .ad
 291 .RS 5n
 292 Successful execution.
 293 .RE
 294
 295 .sp
 296 .ne 2
 297 .na
 298 \fB\fB1\fR\fR
 299 .ad
 300 .RS 5n
 301 \fBEOF\fR on input, or negative width on \fB-W\fR option, or usage error.
 302 .RE
 303
 304 .sp
 305 .ne 2
 306 .na
 307 \fB\fB2\fR\fR
 308 .ad
 309 .RS 5n
 310 Usage error.
 311 .RE
 312
 313 .sp
 314 .ne 2
 315 .na
 316 \fB\fB3\fR\fR
 317 .ad
 318 .RS 5n
 319 User termination (quit).
 320 .RE
 321
 322 .SH SEE ALSO
 323 .sp
 324 .LP
 325 \fBIntro\fR(1), \fBgetopt\fR(1), \fBstrtol\fR(3C), \fBattributes\fR(5),
 326 \fBsignal.h\fR(3HEAD)