asparseopts - parse standard array services command line
options
SYNOPSIS
#include <arraysvcs.h>
asoptinfo_t *asparseopts(int argc, char **argv, int Select, int Control);
DESCRIPTION
The asparseopts function is used to parse standard array
services command line options from a list of strings, pre
sumably the list of arguments to an array services client
program. The results are returned in the form of as
asoptinfo_t structure, which contains parsed, validated
values for the options specified in the argument list, as
well as a list of the arguments that were not recognized
as one of the selected array services options.
The argc and argv arguments are an argument count and
argument list, in the form typically provided to the func
tion main of an ordinary C program.
The Select argument is used to specify which of the "stan
dard" array service command line options are to be
included in this operation. It is formed from the logical
OR of one or more of the following flags, which are
defined in <arraysvcs.h>:
AASSOOIIVV_AARRRRAAYY
Parse the -array option, which takes the name of
an array as a subargument. -a is a synonym for
the -array option.
AASSOOIIVV_AASSHH
Parse the -ash option, which takes an array ses
sion handle as a subargument. The array session
handle may be specified in decimal, octal (if pre
ceded by "0") or hexadecimal (if preceded by
"0x"). -h and -arsess are both synonyms for the
-ash option.
AASSOOIIVV_CCOONNNNEECCTTTTOO
Parse the -connectto option, which takes a connec
tion timeout value as a subargument. The value
must be specified in decimal only. -C is a syn
onym for the -connectto option.
AASSOOIIVV_FFOORRWWAARRDD
Parses the -forward and -direct options, which
specify the array services forwarding mode; -for
ward indicates that array services commands should
be forwarded to their ultimate destination via the
server on the local machine, while -direct means
directly to the remote server. -F is a synonym
for the -forward option and -D is a synonym for
the -direct option.
AASSOOIIVV_LLCCLLKKEEYY
Parse the -localkey option, which takes the
authentication key for the local machine as a sub
argument. -Kl is a synonym for the -localkey
option.
AASSOOIIVV_LLOOCCAALL
Parse the -local option, which indicates that an
array services function should take place only on
the local server, as opposed to being broadcast to
all of the servers in an array, for example. -l
is a synonym for the -local option.
AASSOOIIVV_PPIIDD
Parse the -pid option, which takes a process ID as
a subargument. The process ID should be specified
in decimal only and must be positive. -i and
-process are both synonyms for the -pid option.
AASSOOIIVV_PPOORRTTNNUUMM
Parse the -portnum option, which takes a port num
ber as a subargument. The port number should be
specified in decimal only and must be in the range
1-65535. -p is a synonym for the -portnum option.
AASSOOIIVV_RREEMMKKEEYY
Parse the -remotekey option, which takes the
authentication key for a remote machine as a sub
argument. -Kr is a synonym for the -remotekey
option.
AASSOOIIVV_SSEERRVVEERR
Parse the -server option, which takes the hostname
of an array daemon as a subargument. -s is a syn
onym for the -server option.
AASSOOIIVV_TTIIMMEEOOUUTT
Parse the -timeout option, which takes a timeout
value as a subargument. The value must be speci
fied in decimal only. -t is a synonym for the
-timeout option.
AASSOOIIVV_TTOOKKEENN
If this flag is specified and no invalid arguments
were encountered (in other words, the invalid mem
ber of the returned asoptinfo_t is 0), then a
server token using the parsed options will be cre
ated using asopenserver_from_optinfo(3X).
Parse the -v option, which is used to set a ver
bosity level. The default verbose level is 0, and
each occurrence of -v will increase the level by
1. If an option begins with "v" and is followed
by any number of other non-whitespace characters
(for example, "-vvv"), then the verbose level is
increased by the number of characters following
the hyphen (3 in the case of "-vvv").
The Connect argument is used to specify flags which modify the
parsing behavior. It is formed from the logical OR of zero or
more of the following flags, which are defined in :
ASOIC_LOGERRS
Specifies that syntax errors and other abnormal conditions
should be reported to the normal array services error log
ging destination, which is typically stderr. If this flag
is not specified no error messages will be generated, but
the invalid member of the returned asoptinfo_t can still
be checked to determine if any errors were detected.
ASOIC_NODUPS
Ordinarily, if an option is specified more than once, the
last occurrence of the option in the argument list will
quietly override any previous occurrences of the option.
If the ASOIC_NODUPS flag is specified, then duplicate
occurrences will be called out as errors and the option
will be marked as invalid in the returned asoptinfo_t.
ASOIC_OPTSONLY
This flag causes parsing to stop as soon as an argument
which does not begin with a "-" character is encountered
(not including subarguments to valid options). The
"non-option" argument and all arguments following it will
be returned as unrecognized arguments, even if some of the
subsequent arguments would otherwise have been valid array
services options.
ASOIC_SELONLY
This is similar to AASSOOIICC_OOPPTTSSOONNLLYY with the added restric
tion that parsing stops as soon as any argument which is
not a selected option or the subargument of a selected
option is encountered.
If the argument list is successfully parsed, a pointer to an
asoptinfo_t structure (also defined in ) is
returned. The storage for this structure is allocated using mal
loc(3C) and can be released using the asfreeoptinfo(3X) function.
An asoptinfo_t structure looks similar to this:
typedef struct asoptinfo {
int argc;
char **argv;
int valid;
int options;
asserver_t token;
char *server;
char *array;
askey_t localkey;
askey_t remotekey;
ash_t ash;
pid_t pid;
int portnum;
int timeout;
int connectto;
int verbose; } asoptinfo_t;
The argc and argv members are a count and list, respectively, of
arguments that were not recognized as selected array services
options or their corresponding subarguments.
The valid member is a bitmap used to specify which options were
successfully parsed and are present in the asoptinfo_t. The same
flags used to specify the Select argument to asparseopts are used
to indicate which options are present.
The invalid member is a bitmap of options that were selected and
specified in the argument list, but had values which were invalid
in some way. If the ASOIC_LOGERRS control flag was specified,
then an error message explaining the nature of the problem should
already have been generated. This member also uses the same
flags as valid and Select.
The options member is a bitmap of flags indicating the state of
the various binary options. These include:
ASOIO_FORWARD
If set, command forwarding has been requested. Otherwise,
a direct connection is desired.
ASOIO_LOCAL
If set, the command should be restricted to the local
server. Otherwise, it may be considered eligible for
broadcast to all servers in an array.
IMPORTANT: A flag in options should only be examined if it is
also marked as valid in valid. For example, the state of the
ASOIO_FORWARD flag in options is only meaningful if the
ASOIV_FORWARD flag is set in valid. If the appropriate flag in
valid is not set, then the option should be considered unspeci
fied and a default setting should be used instead.
The token member of asoptinfo_t is not a value directly parsed
from the argument list, but instead a server token created using
the values that were successfully parsed from the argument list.
It will only be created if the ASOIV_TOKEN flag was set in
Select. If it is successfully created, the ASOIV_TOKEN flag will
ASOIV_TOKEN will be set in the invalid member and aserrorcode(3X)
will be set accordingly.
The remaining members of the asoptinfo_t contain the values of
the selected array services options. If a selected option was
specified in the argument list, then its flag in valid will be
set and the corresponding member of asoptinfo_t will contain the
parsed value of that option. If a selected option was not speci
fied in the argument list, then its flag in valid will not be set
and the corresponding member of asoptinfo_t will contain a
default value (generally NULL, 0 or -1, as appropriate). If a
selected option had an invalid value, then its flag will be set
in invalid and the contents of the corresponding member of asopt
info_t are unpredictable.
NOTES
asparseopts is found in the library "libarray.so", and
will be loaded if the option "-larray" is used with cc(1)
or ld(1).
SEE ALSO
aserrorcode(3X), asfreeoptinfo(3X), asopenserver_from_opt
info(3X),
DIAGNOSTICS
If successful, asparseopts returns a pointer to an asopt
info_t structure. If a severe error occurs, NULL is
returned and aserrorcode is set appropriately. If
asparseopts is successful and the AASSOOIIVV_TTOOKKEENN flag of
Select was specified but a server token could not be cre
ated, the pointer to the asoptinfo_t will be returned as
usual, but the AASSOOIIVV_TTOOKKEENN flag of the invalid member will
be set and aserrorcode will contain the error returned by
asopenserver_from_optinfo(3X).
Man(1) output converted with
man2html