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