asparseopts(3x)
asparseopts - parse standard array services command line options
As shipped in IRIX 6.5.5. Unchanged since IRIX 6.5.
NAME 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, 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. 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"). 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; 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 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. 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_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).