asparseopts(3x)asparseopts(3x)NAMEasparseopts - 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, presumably 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 function main of an ordinary C
program.
The Select argument is used to specify which of the "standard" 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>:
ASOIV_ARRAY
Parse the -array option, which takes the name of an array as a
subargument. -a is a synonym for the -array option.
ASOIV_ASH
Parse the -ash option, which takes an array session handle as a
subargument. The array session handle may be specified in
decimal, octal (if preceded by "0") or hexadecimal (if preceded by
"0x"). -h and -arsess are both synonyms for the -ash option.
ASOIV_CONNECTTO
Parse the -connectto option, which takes a connection timeout
value as a subargument. The value must be specified in decimal
only. -C is a synonym for the -connectto option.
ASOIV_FORWARD
Parses the -forward and -direct options, which specify the array
services forwarding mode; -forward indicates that array services
commands should be forwarded to their ultimate destination via the
server on the local machine, while -direct means that array
services commands should be sent directly to the remote server.
-F is a synonym for the -forward option and -D is a synonym for
the -direct option.
Page 1
asparseopts(3x)asparseopts(3x)
ASOIV_LCLKEY
Parse the -localkey option, which takes the authentication key for
the local machine as a subargument. -Kl is a synonym for the
-localkey option.
ASOIV_LOCAL
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.
ASOIV_PID
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.
ASOIV_PORTNUM
Parse the -portnum option, which takes a port number 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.
ASOIV_REMKEY
Parse the -remotekey option, which takes the authentication key
for a remote machine as a subargument. -Kr is a synonym for the
-remotekey option.
ASOIV_SERVER
Parse the -server option, which takes the hostname of an array
daemon as a subargument. -s is a synonym for the -server option.
ASOIV_TIMEOUT
Parse the -timeout option, which takes a timeout value as a
subargument. The value must be specified in decimal only. -t is
a synonym for the -timeout option.
ASOIV_TOKEN
If this flag is specified and no invalid arguments were
encountered (in other words, the invalid member of the returned
asoptinfo_t is 0), then a server token using the parsed options
will be created using asopenserver_from_optinfo(3X).
ASOIV_VERBOSE
Parse the -v option, which is used to set a verbosity 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").
Page 2
asparseopts(3x)asparseopts(3x)
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 <arraysvcs.h>:
ASOIC_LOGERRS
Specifies that syntax errors and other abnormal conditions should
be reported to the normal array services error logging
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 ASOIC_OPTSONLY with the added restriction 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 <arraysvcs.h>) is returned. The storage for
this structure is allocated using malloc(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 invalid;
int options;
asserver_t token;
char *server;
char *array;
askey_t localkey;
askey_t remotekey;
ash_t ash;
pid_t pid;
Page 3
asparseopts(3x)asparseopts(3x)
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 unspecified 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 be set in the valid member of the
asoptinfo_t. Otherwise, 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
Page 4
asparseopts(3x)asparseopts(3x)
corresponding member of asoptinfo_t will contain the parsed value of that
option. If a selected option was not specified 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
asoptinfo_t are unpredictable.
NOTESasparseopts is found in the library "libarray.so", and will be loaded if
the option "-larray" is used with cc(1) or ld(1).
SEE ALSOaserrorcode(3X), asfreeoptinfo(3X), asopenserver_from_optinfo(3X),
DIAGNOSTICS
If successful, asparseopts returns a pointer to an asoptinfo_t structure.
If a severe error occurs, NULL is returned and aserrorcode is set
appropriately. If asparseopts is successful and the ASOIV_TOKEN flag of
Select was specified but a server token could not be created, the pointer
to the asoptinfo_t will be returned as usual, but the ASOIV_TOKEN flag of
the invalid member will be set and aserrorcode will contain the error
returned by asopenserver_from_optinfo(3X).
Page 5
