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



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       getopt, optarg, opterr, optind, optopt -- command option parsing

SSYYNNOOPPSSIISS
       #include <unistd.h>

       int getopt(int _a_r_g_c, char * const _a_r_g_v[], const char *_o_p_t_s_t_r_i_n_g);
       extern char *optarg;
       extern int opterr, optind, optopt;

DDEESSCCRRIIPPTTIIOONN
       The _g_e_t_o_p_t() function is a command-line parser that shall follow
       Utility Syntax Guidelines 3, 4, 5, 6, 7, 9, and 10 in the Base
       Definitions volume of POSIX.1-2008, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x
       _G_u_i_d_e_l_i_n_e_s.

       The parameters _a_r_g_c and _a_r_g_v are the argument count and argument array
       as passed to _m_a_i_n() (see _e_x_e_c()).  The argument _o_p_t_s_t_r_i_n_g is a string
       of recognized option characters; if a character is followed by a
       <colon>, the option takes an argument. All option characters allowed by
       Utility Syntax Guideline 3 are allowed in _o_p_t_s_t_r_i_n_g.  The
       implementation may accept other characters as an extension.

       The variable _o_p_t_i_n_d is the index of the next element of the _a_r_g_v[]
       vector to be processed. It shall be initialized to 1 by the system, and
       _g_e_t_o_p_t() shall update it when it finishes with each element of _a_r_g_v[].
       If the application sets _o_p_t_i_n_d to zero before calling _g_e_t_o_p_t(), the
       behavior is unspecified. When an element of _a_r_g_v[] contains multiple
       option characters, it is unspecified how _g_e_t_o_p_t() determines which
       options have already been processed.

       The _g_e_t_o_p_t() function shall return the next option character (if one is
       found) from _a_r_g_v that matches a character in _o_p_t_s_t_r_i_n_g, if there is one
       that matches. If the option takes an argument, _g_e_t_o_p_t() shall set the
       variable _o_p_t_a_r_g to point to the option-argument as follows:

        1. If the option was the last character in the string pointed to by an
           element of _a_r_g_v, then _o_p_t_a_r_g shall contain the next element of
           _a_r_g_v, and _o_p_t_i_n_d shall be incremented by 2. If the resulting value
           of _o_p_t_i_n_d is greater than _a_r_g_c, this indicates a missing option-
           argument, and _g_e_t_o_p_t() shall return an error indication.

        2. Otherwise, _o_p_t_a_r_g shall point to the string following the option
           character in that element of _a_r_g_v, and _o_p_t_i_n_d shall be incremented
           by 1.

       If, when _g_e_t_o_p_t() is called:

            _a_r_g_v[[ooppttiinndd]]  is a null pointer
           **_a_r_g_v[[ooppttiinndd]]  is not the character --
            _a_r_g_v[[ooppttiinndd]]  points to the string ""--""

       _g_e_t_o_p_t() shall return -1 without changing _o_p_t_i_n_d.  If:

           _a_r_g_v[[ooppttiinndd]]   points to the string ""----""

       _g_e_t_o_p_t() shall return -1 after incrementing _o_p_t_i_n_d.

       If _g_e_t_o_p_t() encounters an option character that is not contained in
       _o_p_t_s_t_r_i_n_g, it shall return the <question-mark> (''??'')  character. If it
       detects a missing option-argument, it shall return the <colon>
       character (''::'') if the first character of _o_p_t_s_t_r_i_n_g was a <colon>, or a
       <question-mark> character (''??'')  otherwise. In either case, _g_e_t_o_p_t()
       shall set the variable _o_p_t_o_p_t to the option character that caused the
       error. If the application has not set the variable _o_p_t_e_r_r to 0 and the
       first character of _o_p_t_s_t_r_i_n_g is not a <colon>, _g_e_t_o_p_t() shall also
       print a diagnostic message to _s_t_d_e_r_r in the format specified for the
       _g_e_t_o_p_t_s utility.

       The _g_e_t_o_p_t() function need not be thread-safe.

RREETTUURRNN VVAALLUUEE
       The _g_e_t_o_p_t() function shall return the next option character specified
       on the command line.

       A <colon> (''::'') shall be returned if _g_e_t_o_p_t() detects a missing
       argument and the first character of _o_p_t_s_t_r_i_n_g was a <colon> (''::'').

       A <question-mark> (''??'')  shall be returned if _g_e_t_o_p_t() encounters an
       option character not in _o_p_t_s_t_r_i_n_g or detects a missing argument and the
       first character of _o_p_t_s_t_r_i_n_g was not a <colon> (''::'').

       Otherwise, _g_e_t_o_p_t() shall return -1 when all command line options are
       parsed.

EERRRROORRSS
       If the application has not set the variable _o_p_t_e_r_r to 0, the first
       character of _o_p_t_s_t_r_i_n_g is not a <colon>, and a write error occurs while
       _g_e_t_o_p_t() is printing a diagnostic message to _s_t_d_e_r_r, then the error
       indicator for _s_t_d_e_r_r shall be set; but _g_e_t_o_p_t() shall still succeed and
       the value of _e_r_r_n_o after _g_e_t_o_p_t() is unspecified.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
   PPaarrssiinngg CCoommmmaanndd LLiinnee OOppttiioonnss
       The following code fragment shows how you might process the arguments
       for a utility that can take the mutually-exclusive options _a and _b and
       the options _f and _o, both of which require arguments:

           ##iinncclluuddee <<ssttddiioo..hh>>
           ##iinncclluuddee <<ssttddlliibb..hh>>
           ##iinncclluuddee <<uunniissttdd..hh>>

           int
           main(int argc, char *argv[ ])
           {
               int c;
               int bflg = 0, aflg = 0, errflg = 0;
               char *ifile;
               char *ofile;
               . . .
               while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
                   switch(c) {
                   case 'a':
                       if (bflg)
                           errflg++;
                       else
                           aflg++;
                       break;
                   case 'b':
                       if (aflg)
                           errflg++;
                       else
                           bflg++;
                       break;
                   case 'f':
                       ifile = optarg;
                       break;
                   case 'o':
                       ofile = optarg;
                       break;
                   case ':':       /* -f or -o without operand */
                       fprintf(stderr,
                           "Option -%c requires an operand\n", optopt);
                       errflg++;
                       break;
                   case '?':
                       fprintf(stderr,
                           "Unrecognized option: '-%c'\n", optopt);
                       errflg++;
                   }
               }
               if (errflg) {
                   fprintf(stderr, "usage: . . . ");
                   exit(2);
               }
               for ( ; optind < argc; optind++) {
                   if (access(argv[optind], R_OK)) {
               . . .
           }

       This code accepts any of the following as equivalent:

           ccmmdd --aaoo aarrgg ppaatthh ppaatthh
           ccmmdd --aa --oo aarrgg ppaatthh ppaatthh
           ccmmdd --oo aarrgg --aa ppaatthh ppaatthh
           ccmmdd --aa --oo aarrgg ---- ppaatthh ppaatthh
           ccmmdd --aa --ooaarrgg ppaatthh ppaatthh
           ccmmdd --aaooaarrgg ppaatthh ppaatthh

   SSeelleeccttiinngg OOppttiioonnss ffrroomm tthhee CCoommmmaanndd LLiinnee
       The following example selects the type of database routines the user
       wants to use based on the _O_p_t_i_o_n_s argument.

           ##iinncclluuddee <<uunniissttdd..hh>>
           ##iinncclluuddee <<ssttrriinngg..hh>>
           ......
           ccoonnsstt cchhaarr **OOppttiioonnss == ""hhddbbttll"";;
           ......
           iinntt ddbbttyyppee,, cc;;
           cchhaarr **sstt;;
           ......
           ddbbttyyppee == 00;;
           wwhhiillee ((((cc == ggeettoopptt((aarrggcc,, aarrggvv,, OOppttiioonnss)))) !!== --11)) {{
               iiff ((((sstt == ssttrrcchhrr((OOppttiioonnss,, cc)))) !!== NNUULLLL)) {{
                   ddbbttyyppee == sstt -- OOppttiioonnss;;
                   bbrreeaakk;;
               }}
           }}

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The _g_e_t_o_p_t() function is only required to support option characters
       included in Utility Syntax Guideline 3. Many historical implementations
       of _g_e_t_o_p_t() support other characters as options. This is an allowed
       extension, but applications that use extensions are not maximally
       portable. Note that support for multi-byte option characters is only
       possible when such characters can be represented as type iinntt.

       While _f_e_r_r_o_r(_s_t_d_e_r_r) may be used to detect failures to write a
       diagnostic to _s_t_d_e_r_r when _g_e_t_o_p_t() returns ''??'', the value of _e_r_r_n_o is
       unspecified in such a condition. Applications desiring more control
       over handling write failures should set _o_p_t_e_r_r to 0 and independently
       perform output to _s_t_d_e_r_r, rather than relying on _g_e_t_o_p_t() to do the
       output.

RRAATTIIOONNAALLEE
       The _o_p_t_o_p_t variable represents historical practice and allows the
       application to obtain the identity of the invalid option.

       The description has been written to make it clear that _g_e_t_o_p_t(), like
       the _g_e_t_o_p_t_s utility, deals with option-arguments whether separated from
       the option by <blank> characters or not. Note that the requirements on
       _g_e_t_o_p_t() and _g_e_t_o_p_t_s are more stringent than the Utility Syntax
       Guidelines.

       The _g_e_t_o_p_t() function shall return -1, rather than EOF, so that
       _<_s_t_d_i_o_._h_> is not required.

       The special significance of a <colon> as the first character of
       _o_p_t_s_t_r_i_n_g makes _g_e_t_o_p_t() consistent with the _g_e_t_o_p_t_s utility. It allows
       an application to make a distinction between a missing argument and an
       incorrect option letter without having to examine the option letter. It
       is true that a missing argument can only be detected in one case, but
       that is a case that has to be considered.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _e_x_e_c

       The Base Definitions volume of POSIX.1-2008, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y
       _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s, <<uunniissttdd..hh>>

       The Shell and Utilities volume of POSIX.1-2008, _g_e_t_o_p_t_s

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be obtained online
       at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                            GETOPT(3)
