Autah-cs.208 net.sources utcsrgv!utzoo!decvax!ucbvax!mhtsa!harpo!utah-cs!thomas Mon Feb 22 10:07:23 1982 scanargs doc .TH SCANARGS 3 "AMPEX CORP." .SH NAME scanargs, qscanargs - formatted conversion from command argument list .SH SYNOPSIS .B "#include " .PP .B "scanargs(argc, argv, format" [, pointer]... .B ) .br .B "int argc;" .br .B "char *argv[];" .br .B "char *format;" .SH DESCRIPTION .I Scanargs reads .I argc arguments from an argument list pointed to by .I argv. It converts the argument list according to the format string, and stores the results of the conversions in its parameters. .I Qscanargs is a smaller and slightly less powerful version. .PP Scanargs expects as its parameters an argument count .I argc, a pointer to an argument list .I argv (see exec(2)), a control string .I format, described below, and a set of .I pointer arguments indicating where the converted output should be stored. .PP The control string contains specifications, which are used to direct interpretation of argument sequences. It consists of the necessary information to describe both an acceptable syntax for the argument list, and the expected meaning of each argument. .PP If the scanning fails it will print a cryptic message telling why it failed, and generate a .I usage message from the control string. .PP The control string is composed of two parts: .PP .B NAME:\ \ The first characters in the string are assumed to be the calling name of the program being executed. This is used for generation of usage messages. .PP .B CONVERSIONS:\ \ Following the name, an optional list of conversion specifications is given, with separating spaces. The structure of a conversion specification: .RS .PP .B "label_key_conversion" .RE .PP consists of a .I label which is a string of non-space characters describing the acceptable argument, a .I key which may be either of .TP 4 .B % The argument is optional. Its absence is ignored. .TP 4 .B ! A required argument. If absent, an error return ensues. .PP and a .I conversion character which indicates the interpretation of the argument; the corresponding pointer parameter must be of a restricted type. .PP The following conversion characters are supported: .TP 4 .B d a decimal integer is expected; the corresponding parameter should be an .I int pointer. .TP 4 .B o an octal integer is expected; the corresponding parameter should be an .I int pointer. .TP 4 .B f a floating point number is expected; the corresponding parameter should be a pointer to a .I float. Not available in .I qscanargs. .TP 4 .B "x X d D o O f F" all numeric types supported by .I scanf(3S) are legal in .I scanargs; .I qscanargs supports all but .B f and .B F formats, and avoids including the large size of the .I scanf routine. .TP 4 .B s a character string is expected; the corresponding parameter should be a .I "pointer to a char pointer." .TP 4 .B - a single character flag is expected; the corresponding parameter should be an .I int pointer. The occurrence of a .B - followed by the character specified in the label will cause the setting of the least significant bit of the integer pointed to by the corresponding parameter. The label may consist of up to sixteen option characters, in which case one of the bits of the integer is independantly set to reflect which one of the flags was present. (The right most character corresponds to the LSB of the integer) Only one option may be chosen from each conversion specification. The bits which are not set will remain in their previous state. The .B - may be followed immediately by more label_key_conversion specifications. These should not be separated by blanks and should not contain any .B - specifications. They will be processed only if the flag argument is scanned. This allows optional specification of parameters corresponding to a flag (e.g. -f file). .PP The scanner will process the control string from left to right, and where there are multiple conversions of the same type, they will be assigned one to one with their order of occurrence in the argument list. Where the order of the arguments is not ambiguous in the control string, they may occur in any order in the argument list. (ie. A decimal number will not be confused with a flag, but may be confused with an octal number or another decimal number. So if an octal and a decimal number are to be arguments, their order will determine their conversion, while a decimal number and a flag as arguments may occur in any order and still be converted correctly.) .PP 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 labels are used directly. The labels should be both terse and descriptive! .bp .PP The .I scanargs function returns 1 when the argument list matched the requirements of the control string, and returns 0 if there was a failure. Parameters for any conversions not matched are left untouched. .br For example, the call .RS .PP int i; double x; char *name; .br scanargs(argc, argv, "program decimal%d floating%F file%s" .in 15 , &i, &x, &name ); .RE .PP in a C program executed by the shell command .RS .PP % program 10 3.5397 inputfile .RE .PP will assign to .I i the value 10, .I x the value 3.5397, and .I name will point to the string "inputfile". .PP If the program was executed by the shell command .RS .PP % program 3.4 5.7 inputfile .RE .PP the following would be printed on the standard error: .RS .PP extra arguments not processed .br usage : program [decimal] [floating] [file] .RE .PP because 3.4 matches the type of 'floating' and inputfile matches the type of 'file', leaving 5.7 unmatched. .br This call could be used for the .I diff command .RS .PP int blanks; int flags; char *file1; char *file2; .br scanargs(argc, argv, "diff b%- efh%- file1!s file2!s" .in 15 , &blanks, &flags, &file1, &file2 ); .RE .PP and would only allow one of either .B "-e -f" or .B -h to be chosen optionally, with .B -b as an independent option. .B File1 and .B file2 are both required. The usage message for this version of .I diff would be .RS .PP usage : diff [-b] -{efh} file1 file2 .RE This call could be used for a simplified version of the .I sed command .RS .PP int efile; int noprint; char *script; char *file1; char *file2; .br scanargs(argc, argv, "sed n%- script%s f%-editfile!s file%s" .in 15 , &noprint, &script, &efile, &file1, &file2 ); .RE .PP If the .B -f option is specified, then a file name must be given as the next string argument. The usage message for this version of .I sed would be .RS .PP usage : sed [-n] [script] [-f editfile] [file] .RE .SH SEE ALSO exec(2), scanf(3S) .SH DIAGNOSTICS By its nature a call to scanargs defines a syntax which may be ambiguous, and although the results may be surprising, they are quite predictable. .SH AUTHOR Gary Newman - Ampex Corporation Heavily modified by Spencer W. Thomas - University of Utah .SH BUGS A flag argument at the end of the format string should be followed by a space. Otherwise the routine which prints the usage message sometimes misses the end of the format string. Arguments conditionalized on a flag are not handled properly. Someday this will be fixed. ----------------------------------------------------------------- gopher://quux.org/ conversion by John Goerzen of http://communication.ucsd.edu/A-News/ This Usenet Oldnews Archive article may be copied and distributed freely, provided: 1. There is no money collected for the text(s) of the articles. 2. The following notice remains appended to each copy: The Usenet Oldnews Archive: Compilation Copyright (C) 1981, 1996 Bruce Jones, Henry Spencer, David Wiseman.