ARGSCAN(3C) COMMAND REFERENCE ARGSCAN(3C) NAME argscan, argsbad - formatted conversion of command arguments SYNOPSIS int argscan(argc, argv, format [, pointer]... ) int argc; char *argv[]; char *format; argsbad(error) char *error DESCRIPTION Argscan converts the given argument list according to the specified format, removing converted arguments from the list and storing the results of the conversions in the locations provided. If successful, argscan returns the number of arguments remaining in the list (excluding argv[0]); otherwise, it will return a -1 after printing messages describing the error encountered and the correct usage of the calling program. Argscan expects as its parameters an argument count argc, a pointer to an argument list argv (see execve(2)), a control string format, described below, and a set of pointer arguments indicating where the converted arguments should be stored. The format string consists of a set of fields and comments separated by spaces or tabs. Each comment is a string not containing percent (%) or exclamation (!) and is printed ver batum in the usage message. It does not affect argument conversion. Each field describes the format of an acceptable argument (or arguments) and has the following structure: key conversion flag(s) whitespace fieldname Key may be either of: % Means the argument is optional -- its absence is ignored. ! Indicates a required argument -- if absent, an error return ensues. Conversion is a single character which specifies the type of argument expected; the corresponding pointer parameter(s) must be of the appropriate type. Printed 5/12/88 1
ARGSCAN(3C) COMMAND REFERENCE ARGSCAN(3C) Flag(s) consists of the alphabetic character(s) from a command argument acceptable under this field. Whitespace is any number of blanks and tabs. It separates flag(s) from fieldname. Fieldname is any string not containing blank, tab, percent (%), or exclamation (!). It is a mnemonic for this field and will appear in the usage message generated from this format string. The following conversion characters are supported: s A character string is expected in the command arguments; the corresponding parameter should be a pointer to a char pointer. If such a string is found, the char pointer will be set to the address of the string. The flag(s) part of this field must be empty. - A dash (-) followed by one and only one of the characters in flag(s) is expected in the command arguments; the corresponding parameter should be an int pointer. Each bit of the integer pointed to corresponds to one character in flag(s), the leftmost character corresponding to the integer's least significant bit. When processed, only the bit corresponding to the flag specified is set; none of the other bits of the integer are modified. Whitespace and fieldname must be empty. + A dash (-) followed by the single character in flag(s) followed in the next argument by an unsigned decimal string is expected in the command arguments; the corresponding parameters should be two int pointers. If the proper information appears in the command arguments, the first integer will be set to 1 and the second to the converted decimal number; otherwise, neither integer is modified. a The command arguments are expected to contain the same information as +, but a character string, rather than a decimal number, is expected; the corresponding parameters should be an int pointer and a pointer to a char pointer. If the proper information appears in the command arguments, the integer is set to 1 and the char pointer is set to the address of the string; otherwise, neither parameter is changed. The scanner will process the format string from left to right, searching for command arguments that match the specified fields. Printed 5/12/88 2
ARGSCAN(3C) COMMAND REFERENCE ARGSCAN(3C) An argument list that does not match the requirements of the control string will cause the printing of a short message telling why, and a message telling what the correct usage is. This usage is gleaned from the control string, and the fieldnames are used directly. The fieldnames should be both terse and descriptive. Consider the following example of a call to argscan for the diff command: int blanks; int flags; char *filename1; char *filename2; argscan(argc, argv, "%-b !-efh !s filename1 !s filename2", &blanks, &flags, &filename1, &filename2 ); This would require one and only one of either -e, -f, or -h to be chosen, with -b as an independent option. Filename1 and filename2 are both required. The usage message for this version of diff would be: Usage: diff [-b] -{efh} filename1 filename2 Argsbad is the subroutine used by argscan to print an error message followed by a usage message. It is made available so that a program can call argscan to make a preliminary check of the command line, then call argsbad passing an appropriate error message (or a pointer to a null string) if any further command line error is discovered. Since argsbad uses the format string and argv[0] passed to argscan, argscan must be called sometime prior to calling argsbad. CAVEATS By its nature a call to argscan defines a syntax which may be ambiguous, and although the results may be surprising, they are predictable. To prevent string and number parameters (conversions a and +) from being gobbled up as string arguments (s conversion), all string conversion fields must follow all string and number parameter fields in the format string. For example: "%-xyz !s zapstr %as string" is illegal; "%-xyz %as string !s zapstr" is legal. No check is made of the correctness of the format string. SEE ALSO execve(2). Printed 5/12/88 3
%%index%% na:336,112; sy:448,1209; de:1657,2124;4189,2774;7371,2345; ca:9716,759; se:10475,111; %%index%%000000000119