4.4BSD/usr/share/man/cat3/getopt.0

GETOPT(3)                   BSD Programmer's Manual                  GETOPT(3)

NNAAMMEE
     ggeettoopptt - get option character from command line argument list

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ssttddlliibb..hh>>

     _e_x_t_e_r_n _c_h_a_r _*_o_p_t_a_r_g
     _e_x_t_e_r_n _i_n_t _o_p_t_i_n_d
     _e_x_t_e_r_n _i_n_t _o_p_t_o_p_t
     _e_x_t_e_r_n _i_n_t _o_p_t_e_r_r
     _e_x_t_e_r_n _i_n_t _o_p_t_r_e_s_e_t

     _i_n_t
     ggeettoopptt(_i_n_t _a_r_g_c, _c_h_a_r _* _c_o_n_s_t _*_a_r_g_v, _c_o_n_s_t _c_h_a_r _*_o_p_t_s_t_r_i_n_g);

DDEESSCCRRIIPPTTIIOONN
     The ggeettoopptt() function incrementally parses a command line argument list
     _a_r_g_v and returns the next _k_n_o_w_n option character.  An option character is
     _k_n_o_w_n if it has been specified in the string of accepted option charac-
     ters, _o_p_t_s_t_r_i_n_g.

     The option string _o_p_t_s_t_r_i_n_g may contain the following elements: individu-
     al characters, and characters followed by a colon to indicate an option
     argument is to follow.  For example, an option string "x" recognizes an
     option ``--xx'', and an option string "x:" recognizes an option and argu-
     ment ``--xx _a_r_g_u_m_e_n_t''. It does not matter to ggeettoopptt() if a following argu-
     ment has leading white space.

     On return from ggeettoopptt(), _o_p_t_a_r_g points to an option argument, if it is
     anticipated, and the variable _o_p_t_i_n_d contains the index to the next _a_r_g_v
     argument for a subsequent call to ggeettoopptt().  The variable _o_p_t_o_p_t saves
     the last _k_n_o_w_n option character returned by ggeettoopptt().

     The variable _o_p_t_e_r_r and _o_p_t_i_n_d are both initialized to 1.  The _o_p_t_i_n_d
     variable may be set to another value before a set of calls to ggeettoopptt() in
     order to skip over more or less argv entries.

     In order to use ggeettoopptt() to evaluate multiple sets of arguments, or to
     evaluate a single set of arguments multiple times, the variable _o_p_t_r_e_s_e_t
     must be set to 1 before the second and each additional set of calls to
     ggeettoopptt(), and the variable _o_p_t_i_n_d must be reinitialized.

     The ggeettoopptt() function returns an EOF when the argument list is exhausted,
     or a non-recognized option is encountered.  The interpretation of options
     in the argument list may be cancelled by the option `--' (double dash)
     which causes ggeettoopptt() to signal the end of argument processing and return
     an EOF. When all options have been processed (i.e., up to the first non-
     option argument), ggeettoopptt() returns EOF.

DDIIAAGGNNOOSSTTIICCSS
     If the ggeettoopptt() function encounters a character not found in the string
     _o_p_t_a_r_g or detects a missing option argument it writes an error message
     and returns `?' to the _s_t_d_e_r_r. Setting _o_p_t_e_r_r to a zero will disable
     these error messages.  If _o_p_t_s_t_r_i_n_g has a leading `:' then then a missing
     option argumet causes a `:' to be returned in addition to supressing any
     error messages.  option argument

     Option arguments are allowed to begin with ``-''; this is reasonable but
     reduces the amount of error checking possible.

EEXXTTEENNSSIIOONNSS
     The _o_p_t_r_e_s_e_t variable was added to make it possible to call the ggeettoopptt()
     function multiple times.  This is an extension to the IEEE Std1003.2
     (``POSIX'') specification.

EEXXAAMMPPLLEE
     extern char *optarg;
     extern int optind;
     int bflag, ch, fd;

     bflag = 0;
     while ((ch = getopt(argc, argv, "bf:")) != EOF)
             switch(ch) {
             case 'b':
                     bflag = 1;
                     break;
             case 'f':
                     if ((fd = open(optarg, O_RDONLY, 0)) < 0) {
                             (void)fprintf(stderr,
                                 "myname: %s: %s\n", optarg, strerror(errno));
                             exit(1);
                     }
                     break;
             case '?':
             default:
                     usage();
     }
     argc -= optind;
     argv += optind;

HHIISSTTOORRYY
     The ggeettoopptt() function appeared 4.3BSD.

BBUUGGSS
     A single dash ``-'' may be specified as an character in _o_p_t_s_t_r_i_n_g, howev-
     er it should _n_e_v_e_r have an argument associated with it.  This allows
     ggeettoopptt() to be used with programs that expect ``-'' as an option flag.
     This practice is wrong, and should not be used in any current develop-
     ment.  It is provided for backward compatibility _o_n_l_y. By default, a sin-
     gle dash causes ggeettoopptt() to return EOF. This is, we believe, compatible
     with System V.

     It is also possible to handle digits as option letters.  This allows
     ggeettoopptt() to be used with programs that expect a number (``-3'') as an op-
     tion.  This practice is wrong, and should not be used in any current de-
     velopment.  It is provided for backward compatibility _o_n_l_y. The following
     code fragment works in most cases.

           int length;
           char *p;

           while ((c = getopt(argc, argv, "0123456789")) != EOF)
                   switch (c) {
                   case '0': case '1': case '2': case '3': case '4':
                   case '5': case '6': case '7': case '8': case '9':
                           p = argv[optind - 1];
                           if (p[0] == '-' && p[1] == ch && !p[2])
                                   length = atoi(++p);
                           else
                                   length = atoi(argv[optind] + 1);
                           break;
                   }
           }

4.3 Berkeley Distribution        June 4, 1993                                2