valrange(1)

NAME

     ckrange, errange, helprange,  valrange  -  prompts  for  and
     validates an integer

SYNOPSIS

     ckrange [-Q] [-W width] [-l lower] [-u upper]  [-b base]  [-
     d default]  [-h help]  [-e error]  [-p prompt]  [  -k pid [-
     s signal]]

     /usr/sadm/bin/errange [-W width]  [-e error]  [-l lower]  [-
     u upper] [-b base]

     /usr/sadm/bin/helprange [-W width] [-h help]  [-l lower]  [-
     u upper] [-b base]

     /usr/sadm/bin/valrange [-l lower] [-u upper] [-b base] input

DESCRIPTION

     The ckrange utility prompts a user for an integer between  a
     specified  range  and  determines  whether  this response is
     valid. It defines, among  other  things,  a  prompt  message
     whose  response should be an integer in the range specified,
     text for help and error messages, and a default value (which
     is returned if the user responds with a <RETURN>).

     This command also defines a range for valid input. If either
     the  lower  or upper limit is left undefined, then the range
     is bounded on only one end.

     All messages are limited in length to 79 characters and  are
     formatted automatically. Tabs and newlines are removed after
     a single whitespace character in a message  definition,  but
     spaces are not removed. When a tilde is placed at the begin-
     ning or end of a message definition, the default  text  will
     be inserted at that point, allowing both custom text and the
     default text to be displayed.

     If the prompt, help or error message  is  not  defined,  the
     default message (as defined under EXAMPLES) is displayed.

     Three visual tool modules are linked to the ckrange command.
     They  are  errange (which formats and displays an error mes-
     sage on the standard output), helprange (which  formats  and
     displays  a  help  message on the standard output), and val-
     range (which validates a response). These modules should  be
     used  in  conjunction with Framed Access Command Environment
     (FACE) objects. In this instance, the  FACE  object  defines
     the prompt.

     Note: Negative "input" arguments confuse getopt in valrange.
     By  inserting  a  "-" before the argument, getopt processing
     will stop. See getopt(1) and intro(1) about getopt parameter
     handling.  getopt is used to parse positional parameters and
     to check for legal options.

OPTIONS

     The following options are supported:

     -b base
           Defines the base for input. Must be 2 to  36,  default
           is  10.  Base  conversion  uses  strtol(3C). Output is
           always base 10.

     -d default
           Defines the default value as default. default is  con-
           verted using strtol(3C) in the desired base. Any char-
           acters invalid in the specified  base  will  terminate
           the strtol conversion without error.

     -e error
           Defines the error message as  error.

     -h help
           Defines the help message as  help.

     -k pid
           Specifies that process ID pid is to be sent  a  signal
           if the user chooses to quit.

     -l lower
           Defines the lower limit of the range as lower. Default
           is the machine's largest negative long.

     -p prompt
           Defines the prompt message as prompt.

     -Q    Specifies that quit will not be  allowed  as  a  valid
           response.

     -s signal
           Specifies that the process ID pid defined with the  -k
           option  is  to  be  sent  signal  signal  when quit is
           chosen. If no signal is specified,  SIGTERM is used.

     -u upper
           Defines the upper limit of the range as upper. Default
           is the machine's largest positive long.

     -W width
           Specifies that prompt, help and error messages will be
           formatted to a line length of width.

OPERANDS

     The following operand is supported:

     input Input to be verified against upper  and  lower  limits
           and base.

EXAMPLES

     Example 1: Default base 10 prompt

     The default base 10 prompt for ckrange is:

     example% ckrange
     Enter an integer between lower_bound and
     upper_bound [lower_bound-upper_bound,?,q]:

     Example 2: Default base 10 error message

     The default base 10 error message is:

     example% /usr/sadm/bin/errange
     ERROR: Please enter an integer between lower_bound \
          and upper_bound.

     Example 3: Default base 10 help message

     The default base 10 help message is:

     example% /usr/sadm/bin/helprange
     Please enter an integer between lower_bound and upper_bound.

     Example 4: Changing messages for a base other than 10

     The messages are changed from  ``integer''  to  ``base  base
     integer''  if the base is set to a number other than 10. For
     example,

     example% /usr/sadm/bin/helprange -b 36

     Example 5: Using the quit option

     When the quit option is chosen (and allowed), q is  returned
     along  with  the  return  code 3. Quit input gets a trailing
     newline.

     Example 6: Using the valrange module

     The valrange module will produce a usage message on  stderr.
     It returns  0 for success and non-zero for failure.

     example% /usr/sadm/bin/valrange
     usage: valrange [-l lower] [-u upper] [-b base] input

EXIT STATUS

     The following exit values are returned:

     0     Successful execution.

     1     EOF on input, or negative width on -W option, or usage
           error.

     2     Usage error.

     3     User termination (quit).

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWcsu                     |
    |_____________________________|_____________________________|

SEE ALSO

     intro(1),  face(1),  getopt(1),  strtol(3C),  attributes(5),
     signal(3HEAD)