usr/src/man/man1/ckitem.1

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1992, 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 CKITEM 1 "Sep 14, 1992"
   7 .SH NAME
   8 ckitem, erritem, helpitem \- build a menu; prompt for and return a menu item
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBckitem\fR [\fB-Q\fR] [\fB-W\fR \fIwidth\fR] [\fB-uno\fR] [\fB-f\fR \fIfilename\fR] [\fB-l\fR \fIlabel\fR]
  13      [ [\fB-i\fR \fIinvis\fR] [,]...] [\fB-m\fR \fImax\fR] [\fB-d\fR \fIdefault\fR] [\fB-h\fR \fIhelp\fR]
  14      [\fB-e\fR \fI error\fR] [\fB-p\fR \fIprompt\fR] [\fB-k\fR \fIpid\fR [\fB-s\fR \fIsignal\fR]]
  15      [\fIchoice\fR [...]]
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fB/usr/sadm/bin/erritem\fR [\fB-W\fR \fIwidth\fR] [\fB-e\fR \fIerror\fR] [\fIchoice\fR [..]]
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fB/usr/sadm/bin/helpitem\fR [\fB-W\fR \fIwidth\fR] [\fB-h\fR \fIhelp\fR] [\fIchoice\fR [..]]
  26 .fi
  27
  28 .SH DESCRIPTION
  29 .sp
  30 .LP
  31 The \fBckitem\fR utility builds a menu and prompts the user to choose one item
  32 from a menu of items. It then  verifies the response. Options for this command
  33 define, among other things, a prompt message whose response will be a menu
  34 item, text for help and error messages, and a default value (which will be
  35 returned if the user responds with a carriage return).
  36 .sp
  37 .LP
  38 By default, the menu is formatted so that each item is prepended by a number
  39 and is printed in columns across the terminal. Column length is determined by
  40 the longest choice. Items are alphabetized.
  41 .sp
  42 .LP
  43 All messages are limited in length to 70 characters and are formatted
  44 automatically. Any white space used in the definition (including newline) is
  45 stripped. The \fB-W\fR option cancels the automatic formatting. When a tilde is
  46 placed at the beginning or end of a message definition, the default text will
  47 be inserted at that point, allowing both custom text and the default text to be
  48 displayed.
  49 .sp
  50 .LP
  51 If the prompt, help or error message is not defined, the default message (as
  52 defined under \fBNOTES\fR) will be displayed.
  53 .sp
  54 .LP
  55 Two visual tool modules are linked to the \fBckitem\fR command. They are
  56 \fBerritem\fR (which formats and displays an error message) and \fBhelpitem\fR
  57 (which formats and displays a help message). These modules should be used in
  58 conjunction with \fBFML\fR objects. In this instance, the \fBFML\fR object
  59 defines the prompt. When \fIchoice\fR is defined in these modules, the messages
  60 will describe the available menu choice (or choices).
  61 .SH OPTIONS
  62 .sp
  63 .LP
  64 The following options are supported:
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fB-d\fR\fI default\fR\fR
  69 .ad
  70 .RS 15n
  71 Define the default value as \fIdefault\fR. The default is not validated and so
  72 does not have to meet any criteria.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fB-e\fR\fI error\fR\fR
  79 .ad
  80 .RS 15n
  81 Define the error message as \fI error\fR.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fB-f\fR\fI filename\fR\fR
  88 .ad
  89 .RS 15n
  90 Define a file, \fIfilename\fR, which contains a list of menu items to be
  91 displayed. (The format of this file is: \fBtoken<tab>description\fR. Lines
  92 beginning with a pound sign (#) are designated as comments and ignored.)
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fB-h\fR\fI help\fR\fR
  99 .ad
 100 .RS 15n
 101 Define the help messages as \fI help\fR.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fB-i\fR\fI invis\fR\fR
 108 .ad
 109 .RS 15n
 110 Define invisible menu choices (those which will not be printed in the menu).
 111 (For example, ``all'' used as an invisible choice would mean it is a legal
 112 option but does not appear in the menu. Any number of invisible choices may be
 113 defined.) Invisible choices should be made known to a user either in the prompt
 114 or in a help message.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fB-k\fR\fI pid\fR\fR
 121 .ad
 122 .RS 15n
 123 Specify that the process \fBID\fR \fIpid\fR is to be sent a signal if the user
 124 chooses to abort.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fB-l\fR\fI label\fR\fR
 131 .ad
 132 .RS 15n
 133 Define a label, \fIlabel\fR, to print above the menu.
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fB-m\fR\fI max\fR\fR
 140 .ad
 141 .RS 15n
 142 Define the maximum number of menu choices that the user can choose. The default
 143 is 1.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fB-n\fR\fR
 150 .ad
 151 .RS 15n
 152 Specify that menu items should not be displayed in alphabetical order.
 153 .RE
 154
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fB-o\fR\fR
 159 .ad
 160 .RS 15n
 161 Specify that only one menu token will be returned.
 162 .RE
 163
 164 .sp
 165 .ne 2
 166 .na
 167 \fB\fB-p\fR\fI prompt\fR\fR
 168 .ad
 169 .RS 15n
 170 Define the prompt message as \fIprompt\fR.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fB-Q\fR\fR
 177 .ad
 178 .RS 15n
 179 Specify that quit will not be allowed as a valid response.
 180 .RE
 181
 182 .sp
 183 .ne 2
 184 .na
 185 \fB\fB-s\fR\fI signal\fR\fR
 186 .ad
 187 .RS 15n
 188 Specify that process \fBID\fR \fIpid\fR defined with the \fB-k\fR option is to
 189 be sent signal \fI signal\fR when quit is chosen. If no signal is specified,
 190 \fBSIGTERM\fR is used.
 191 .RE
 192
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fB-u\fR\fR
 197 .ad
 198 .RS 15n
 199 Specify that menu items should be displayed as an unnumbered list.
 200 .RE
 201
 202 .sp
 203 .ne 2
 204 .na
 205 \fB\fB-W\fR\fI width\fR\fR
 206 .ad
 207 .RS 15n
 208 Specify that prompt, help and error messages will be formatted to a line length
 209 of \fIwidth\fR.
 210 .RE
 211
 212 .SH OPERANDS
 213 .sp
 214 .LP
 215 The following operand is supported:
 216 .sp
 217 .ne 2
 218 .na
 219 \fB\fIchoice\fR\fR
 220 .ad
 221 .RS 10n
 222 Define menu items. Items should be separated by white space or newline.
 223 .RE
 224
 225 .SH EXIT STATUS
 226 .sp
 227 .LP
 228 The following exit values are returned:
 229 .sp
 230 .ne 2
 231 .na
 232 \fB\fB0\fR\fR
 233 .ad
 234 .RS 5n
 235 Successful execution.
 236 .RE
 237
 238 .sp
 239 .ne 2
 240 .na
 241 \fB\fB1\fR\fR
 242 .ad
 243 .RS 5n
 244 \fBEOF\fR on input, or negative width on \fB-W\fR option, or inability to open
 245 file on \fB-f\fR option, or usage error.
 246 .RE
 247
 248 .sp
 249 .ne 2
 250 .na
 251 \fB\fB3\fR\fR
 252 .ad
 253 .RS 5n
 254 User termination (quit).
 255 .RE
 256
 257 .sp
 258 .ne 2
 259 .na
 260 \fB\fB4\fR\fR
 261 .ad
 262 .RS 5n
 263 No choices from which to choose.
 264 .RE
 265
 266 .SH SEE ALSO
 267 .sp
 268 .LP
 269 \fBattributes\fR(5)
 270 .SH NOTES
 271 .sp
 272 .LP
 273 The user may input the number of the menu item if choices are numbered or as
 274 much of the string required for a unique identification of the item. Long menus
 275 are paged with 10 items per page.
 276 .sp
 277 .LP
 278 When menu entries are defined both in a file (by using the \fB-f\fR option) and
 279 also on the command line, they are usually combined alphabetically. However, if
 280 the \fB-n\fR option is used to suppress  alphabetical ordering, then the
 281 entries defined in the file are shown first, followed by the options defined on
 282 the command line.
 283 .sp
 284 .LP
 285 The default prompt for \fBckitem\fR is:
 286 .sp
 287 .in +2
 288 .nf
 289 Enter selection [?,??,q]:
 290 .fi
 291 .in -2
 292 .sp
 293
 294 .sp
 295 .LP
 296 One question mark will give a help message and then redisplay the prompt. Two
 297 question marks will give a help message and then redisplay the menu label, the
 298 menu and the prompt.
 299 .sp
 300 .LP
 301 The default error message if you typed a number is:
 302 .sp
 303 .in +2
 304 .nf
 305 ERROR: Bad numeric choice specification
 306 .fi
 307 .in -2
 308 .sp
 309
 310 .sp
 311 .LP
 312 The default error message if you typed a string is:
 313 .sp
 314 .in +2
 315 .nf
 316 ERROR: Entry does not match available menu selection. Enter the number
 317 of the menu item you wish to select, the token which is associated
 318 with the menu item, or a partial string which uniquely identifies the
 319 token for the menu item. Enter ?? to reprint the menu.
 320 .fi
 321 .in -2
 322 .sp
 323
 324 .sp
 325 .LP
 326 The default help message is:
 327 .sp
 328 .in +2
 329 .nf
 330 Enter the number of the menu item you wish to select, the token
 331 which is associated with the menu item, or a partial string which
 332 uniquely identifies the token for the menu item. Enter ? to
 333 reprint the menu.
 334 .fi
 335 .in -2
 336 .sp
 337
 338 .sp
 339 .LP
 340 When the quit option is chosen (and allowed), \fBq\fR is returned along with
 341 the return code \fB3\fR.