Return to getflags.3 CVS log

Up to [Research Unix] / researchv10dc / man / adm / man3

Annotation of researchv10dc/man/adm/man3/getflags.3, revision 1.1.1.1

1.1       root        1: .TH GETFLAGS 3
                      2: .CT 2 data_man
                      3: .SH NAME
                      4: getflags \(mi process flag arguments in argv
                      5: .SH SYNOPSIS
                      6: .nf
                      7: #include </usr/include/getflags.h>
                      8: .PP
                      9: .B int getflags(argc, argv, flags)
                     10: .B char **argv, *flags;
                     11: .PP
                     12: .B usage(tail)
                     13: .B char *tail;
                     14: .PP
                     15: .B extern char **flag[], cmdline[], *cmdname, *flagset[];
                     16: .fi
                     17: .SH DESCRIPTION
                     18: .I Getflags
                     19: digests an argument vector
                     20: .IR argv ,
                     21: finding flag arguments listed in
                     22: .IR flags .
                     23: .I Flags
                     24: is a string of flag letters.
                     25: A letter followed by a colon and a number
                     26: is expected to have the given number of parameters.
                     27: A flag argument starts with
                     28: .RB ` - '
                     29: and is followed by any number of flag letters.
                     30: A flag with one or more parameters must be the last flag in an argument.
                     31: If any characters follow it, they are the flag's first parameter.  Otherwise
                     32: the following argument is the first parameter.  Subsequent parameters are taken
                     33: from subsequent arguments.
                     34: .PP
                     35: The global array
                     36: .I flag
                     37: is set to point to an array of parameters for each flag found.
                     38: Thus, if flag
                     39: .B -x
                     40: was seen,
                     41: .B flag['x']
                     42: is non-zero, and
                     43: .B flag['x'][i]
                     44: is the flag's
                     45: .IR i th
                     46: parameter.
                     47: If flag
                     48: .B -x
                     49: has no parameters
                     50: .BR flag['x']==flagset .
                     51: Flags not found
                     52: are marked with a zero.
                     53: Flags and their parameters are deleted from
                     54: .I argv.
                     55: .I Getflags
                     56: returns the adjusted argument count.
                     57: .PP
                     58: .I Getflags
                     59: stops scanning for flags upon encountering a non-flag argument,
                     60: or an argument whose only character is
                     61: .RB ` - ',
                     62: which argument is deleted.
                     63: .PP
                     64: .I Getflags
                     65: places a pointer to 
                     66: .I argv[0]
                     67: in the external variable
                     68: .I cmdname.
                     69: It also concatenates the original members of
                     70: .IR argv ,
                     71: separated by spaces, and places the result in the external array
                     72: .IR cmdline .
                     73: .PP
                     74: .I Usage
                     75: constructs a usage message, prints it on the standard error file,
                     76: and exits with status 1.
                     77: The command name printed is
                     78: .IR argv[0] .
                     79: Appropriate flag usage syntax is generated from
                     80: .IR flags .
                     81: As an aid,
                     82: explanatory information about flag parameters may be included in
                     83: .I flags
                     84: in square brackets as in the example.
                     85: .I Tail
                     86: is printed at the end of the message.
                     87: If
                     88: .I getflags
                     89: encountered an error,
                     90: .I usage
                     91: tries to indicate the cause.
                     92: .SH EXAMPLES
                     93: .EX
                     94:        main(argc, argv)
                     95:        char *argv[];
                     96:        {
                     97:                if((argc=getflags(argc, argv, "vinclbhse:1[expr]", 1))==-1)
                     98:                        usage("[file ...]");
                     99:        }
                    100: .EE
                    101: might print:
                    102: .EX
                    103:        Illegal flag -u
                    104:        Usage: grep [-vinclbhs] [-e expr] [file ...]
                    105: .EE
                    106: .SH "SEE ALSO"
                    107: .IR getopt (3)
                    108: .SH DIAGNOSTICS
                    109: .I Getflags
                    110: returns \-1 on error:
                    111: a syntax error in
                    112: .I flags,
                    113: setting a flag more than once, setting a flag not mentioned
                    114: in
                    115: .IR flags ,
                    116: or running out of argv while collecting a flag's parameters.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.