Unix validation tools: sysvtools.pl description

The sysvtools.pl perl program is a wrapper in order to act like the validation tool with the name it was called with. The necessary symbolic links are created during the installation, but you can also add the links you need manually.

The most line consuming work of the program is the command line arguments validation and conversion. The main task (create and run the module) is done in a handful of lines, because you must only call the module's constructor with the defined options and then perform the run() method.

When you look at the source code, you will see, that I didn't use the Perl standard modules for this task. Of course I did it intentionally (did I mention, that - like almost all programmers - I'm lazy? If I can use existing modules, I do it).

The result is a handmade options parser. It's missing the feature to put options together like -rwx (permissions in ckpath). At the moment I wonder how to implement that in my parser. Maybe, it will come some day.

There are no manual pages according to each tool. The manual for all tools is available with man sysvtools.

sysvtools.pl - the program to call the SysV validation tools. This program is designed to run under the names of their respective Unix tool names as described below.

  ckcont [-w width] [-h help] [-e error] [-p prompt] message

  ckdate [-Q] [-w width] [-d default] [-h help] [-e error] [-p prompt]
    [-k pid [-s signal]] [-f format]
  errdate [-w width] [-e error] [-f format]
  helpdate [-w width] [-h help] [-f format]
  valdate [-f format] input

  ckgid [-Q] [-w width] [-d default] [-h help] [-e error] [-p prompt]
    [-k pid [-s signal]] [-m]
  errgid [-w width] [-e error]
  helpgid [-w width] [-h help] [-m]
  valgid input

  ckint [-Q] [-w width] [-d default] [-h help] [-e error] [-p prompt]
    [-k pid [-s signal]] [-b base]
  errint [-w width] [-e error] [-b base]
  helpint [-w width] [-h help] [-b base]
  valint [-b base] input

  ckitem [-Q] [-w width] [-d default] [-h help] [-e error] [-p prompt]
    [-k pid [-s signal]] [-uno] [-f filename] [-l label] [-i invis [...]]
    [-m max] [choice [...]]
  erritem [-w width] [-e error] [choice [...]]
  helpitem [-w width] [-h help] [choice [...]]

  ckkeywd [-Q] [-w width] [-d default] [-h help] [-e error] [-p prompt]
    [-k pid [-s signal]] keyword [...]

  ckpath [-Q] [-w width] [-d default] [-h help] [-e error] [-p prompt]
    [-k pid [-s signal]] [-a|l] [-b|c|f|y] [-n|o[z]] [-rtwx]
  errpath [-w width] [-e error] [-a|l] [-b|c|f|y] [-n|o[z]] [-rtwx]
  helppath [-w width] [-h help] [-a|l] [-b|c|f|y] [-n|o[z]] [-rtwx]
  valpath [-a|l] [-b|c|f|y] [-n|o[z]] [-rtwx] input

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

  ckstr [-Q] [-w width] [-d default] [-h help] [-e error] [-p prompt]
    [-k pid [-s signal]] [-l length] [[-r regexp] [...]]
  errstr [-w width] [-e error] [-l length] [[-r regexp] [...]]
  helpstr [-w width] [-h help] [-l length] [[-r regexp] [...]]
  valstr [-l length] [[-r regexp] [...]] input

  cktime [-Q] [-w width] [-d default] [-h help] [-e error] [-p prompt]
    [-k pid [-s signal]] [-f format]
  errtime [-w width] [-e error] [-f format]
  helptime [-w width] [-h help] [-f format]
  valtime [-f format] input

  ckuid [-Q] [-w width] [-d default] [-h help] [-e error] [-p prompt]
    [-k pid [-s signal]] [-m]
  erruid [-w width] [-e error]
  helpuid [-w width] [-h help] [-m]
  valuid input

  ckyorn [-Q] [-w width] [-d default] [-h help] [-e error] [-p prompt]
    [-k pid [-s signal]]
  erryorn [-w width] [-e error]
  helyorn [-w width] [-h help]
  valyorn input

This documentation describes the version 0.3 of the sysvtools.pl program.

The ck* utilities prompt the user for an input and validate the response. The type of expected input is depending on the utility. The utilities define prompt, error and help messages and standard keys to control the program flow.

The err* utilities print the defined or a standard error message and exit.

The help* utilities print the defined or a standard help message and exit.

The val* utilities validate the input according to the given options and exit with an appropriate return code. They do not print the input value.

All messages are limited in length to 70 characters per line and are formatted automatically. Any whitespace used in the definition (including newline) is stripped. The output width can be overwritten using the -W option. When a tilde is placed at the beginning or the end of a message definition, the default message will be inserted at that point.

Help is requested by the user response '?', the utilities quit when quit is choosen (input depending on the language) if there is no -Q option defined.

The error message is printed when the user request does not match the requested input type and criterias.

ckcont
This utility is an extension to the tools available in SysV unix systems. It simply prints the prompt message and waits for a RETURN. I missed it and added it to my collection. One can use it to let the user read messages printed out by programs and continue with work when ready.

ckdate
The user response must match the given format (or the default format) for a date.

ckgid
The user response should be an existing group name.

ckint
The user response should be an integer, optionally appropriate to a defined base. The output is always the value to base 10.

ckitem
This utility builds a menu and then verifies the response. By default the menu is formatted so that each item is prepended by a number and is printed in columns across the terminal with 10 items per screen. The items are sorted alphabetically. This behaviour can be overwritten by command line options.

If the choices list is greater than a 10 lines height, the user can page down using the RETURN key or stop the display of choices using CTRL-d. The utility will then show the prompt message. The '??' response reprints the menu starting at the first page.

ckkeywd
The user response must be one of the list of the defined keywords.

ckpath
The user response must be a pathname which obeys the criteria specified options. If no criteria is defined, the pathname must be a regular file that does not yet exist.

ckrange
The user response should be an integer, optionally appropriate to a defined base. The input is validated against the defined lower and upper bounds. If only one limit is defined, then the range is bounded on only one end. The output is always the value to base 10.

ckstr
The user response must match the defined regular expression and be no longer than the length specified. If no regular expression is given, valid input must be a string with a length less than or equal to the length defined with no internal, leading or trailing white space. If no length is defined, the length is not checked.

cktime
The user response must match the given format (or the default format) for a time.

ckuid
The user response should be an existing user login name.

ckyorn
The user response must be a yes or no answer.

The following command line options are supported by all utilities:

-Q
Specifies that quit will not be allowed as a valid response. the ckcont utility will ignore this option because it's useless here.

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

-d default
Defines the default value to default. The default value does not have to meet any criteria. If the user responds with a RETURN and the default value is defined, this value is returned. This option is ignored in the ckcont utility.

-e error
Defines the error message as error

-h help
Defines the help message as help

-p prompt
Defines the prompt message as prompt

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

-s signal
Specifies that the process ID pid defined with the -k option is to be sent the signal signal when quit is choosen. If no signal is specified, SIGTERM is used. The signal can be defined as integer or as signal name.

The following option is supported be the *date utilities:

-f format
Specifies the format against the input will be verified. Possible formats and their definitions are:
%b
abbreviated month name (jan, feb, mar)

%B
full month name

%d
day of month (01 - 31)

%D
date as %m/%d/%y (the default format)

%e
day of month (1 - 31; single digits are preceeded by a blank)

%h
abbreviated month name, identical to %b

%m
month number (01 - 12)

%y
year within century (for instance 08)

%Y
year as CCYY (for instance 2008)

The following option is supported be the *gid utilities:

-m
Displays a list of all groups when help is requested or when the user makes an error.

The following option is supported be the *int utilities:

-b base
Defines the base for input. It must be 2 to 36, default is 10.

The following options are supported be the *item utilities:

-f filename
Define a file filename, which contains a list of menu items to be displayed. The format of each line in this file is: token<TAB>description. Lines beginning with a pound sign (#) are designated as comments and ignored.

-i invis
Define invisible menu choices, which will not be displayed in the menu. For example, 'all' used as an invisible choice would mean it is a legal option but does not appear in the menu. This option may be used multiple times. Invisible choices should be made known to the user either in the prompt or in a help message.

-l label
Define a label label to print above the menu. Per default no label is printed.

-m max
Defines the maximum number of choices the user can choose. The default is 1.

-n
Specify that the menu items should not be displayed in alphabetical order.

-o
Specify that only one menu token will be returned.

-u
Specify that menu items should be printed as an unnumbered list.

The following options are supported be the *path utilities:

-a
Pathname must be an absolute path

-b
Pathname must be a block special file

-c
Pathname must be a character special file

-f
Pathname must be a regular file

-l
Pathname must be a relative path

-n
Pathname must not exist (must be new)

-o
Pathname must exist (must be old)

-r
Pathname must be readable

-t
Pathname must be creatable (touchable). Pathname will be created if it does not already exist (see BUGS)

-w
Pathname must be writable

-x
Pathname must be executable

-y
Pathname must be a directory

-z
Pathname must be a file having a size greater than zero bytes

The following options are supported be the *range utilities:

-b base
Defines the base for input. It must be 2 to 36, default is 10.

-l lower
Defines the lower limit of the range as lower. Default is the machine's largest negative long. The lower is read as a value of base -b base.

-u upper
Defines the upper limit of the range as upper. Default is the machine's largest positive long. The upper is read as a value of base -b base.

The following options are supported be the *str utilities:

-l length
pecifies the maximum length of the input.

-r regex
Specifies a regular expression regex against which the input should be validated. May include white spaces. If multiple expressions are defined, the answer needs to match only one of them.

The following option is supported be the *time utilities:

-f format
Specifies the format against the input will be verified. Possible formats and their definitions are:
%H
hour (00 - 23)

%I
hour (00 - 12)

%M
minute (00 - 59)

%p
ante meridian or post meridian

%r
time as %I:%M:%S %p

%R
time as %H:%M (the default format)

%S
seconds (00 - 59)

%T
time as %H:%M:%S

The following option is supported be the *uid utilities:

-m
Displays a list of all logins when help is requested or when the user makes an error.

The return codes of this program differ in some ways from the exit status of their unix equivalents. In some cases I did not really understand the differences between some of the codes (for example return code 2 and 4 in ckpath), in other cases (garbled format for ckdate or cktime, empty choices list for ckitem) I proceed all option checks in one method and therefore make no difference in handling error situations.

The program will return the following exit values:

0
Successful execution

1
Usage error detected by the getArgs method of this program (unknown program name, invalid options or missing option values)

2
Usage error detected by the JT::CLI::SysVTools validation methods (garbled date or time formats, invalid values for options, mutually exclusive options). Invalid input for the val* tools.

3
User termination (quit)

Combined options like -rwx are not possible, they will produce an error. If the -t option is defined for *path utilities, the file will not be created.

If you find another 'unwanted feature' in this program, please contact me and send me a detailed error description. A 'The program does not work' message will be ignored ;-)

I tried to check all variants of options for the different utilities and verified the program behaviour against the tools on a Solaris10 machine, but I may have missed some tests. The message catalogues delivered with this program will provide messages, which are not 100% unique to the originals. If you want to have the messages to be changed, contact me - or better, help me. Send me the fixed message source files and I will build new catalogues.