home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3c / getopt.z / getopt
Encoding:
Text File  |  2002-10-03  |  10.7 KB  |  199 lines
  1.  
  2.  
  3.  
  4. ggggeeeettttoooopppptttt((((3333CCCC))))                                                          ggggeeeettttoooopppptttt((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _gggg_eeee_tttt_oooo_pppp_tttt - get option letter from argument vector
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_uuuu_nnnn_iiii_ssss_tttt_dddd_...._hhhh_>>>>
  13.  
  14.      _iiii_nnnn_tttt _gggg_eeee_tttt_oooo_pppp_tttt _((((_iiii_nnnn_tttt _aaaa_rrrr_gggg_cccc_,,,, _cccc_hhhh_aaaa_rrrr _**** _cccc_oooo_nnnn_ssss_tttt _aaaa_rrrr_gggg_vvvv_[[[[_]]]]_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_oooo_pppp_tttt_ssss_tttt_rrrr_iiii_nnnn_gggg_))))_;;;;
  15.  
  16.      _eeee_xxxx_tttt_eeee_rrrr_nnnn _cccc_hhhh_aaaa_rrrr _****_oooo_pppp_tttt_aaaa_rrrr_gggg_;;;;
  17.  
  18.      _eeee_xxxx_tttt_eeee_rrrr_nnnn _iiii_nnnn_tttt _oooo_pppp_tttt_iiii_nnnn_dddd_,,,, _oooo_pppp_tttt_eeee_rrrr_rrrr_,,,, _oooo_pppp_tttt_oooo_pppp_tttt_;;;;
  19.  
  20.      _eeee_xxxx_tttt_eeee_rrrr_nnnn _vvvv_oooo_iiii_dddd _gggg_eeee_tttt_oooo_pppp_tttt_rrrr_eeee_ssss_eeee_tttt _((((_vvvv_oooo_iiii_dddd_))))_;;;;
  21.  
  22. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  23.      _gggg_eeee_tttt_oooo_pppp_tttt returns the next option letter in _a_r_g_v that matches a letter in
  24.      _o_p_t_s_t_r_i_n_g.  It supports all the rules of the command syntax standard [see
  25.      _iiii_nnnn_tttt_rrrr_oooo(1)].  Since all new commands are intended to adhere to the command
  26.      syntax standard, they should use _gggg_eeee_tttt_oooo_pppp_tttt_ssss(1), _gggg_eeee_tttt_oooo_pppp_tttt(3C), or _gggg_eeee_tttt_ssss_uuuu_bbbb_oooo_pppp_tttt(3C)
  27.      to parse positional parameters and check for options that are legal for
  28.      that command.
  29.  
  30.      _o_p_t_s_t_r_i_n_g must contain the option letters that the command using _gggg_eeee_tttt_oooo_pppp_tttt
  31.      will recognize.  If a letter is followed by a colon, the option is
  32.      expected to have an argument, or group of arguments, which may be
  33.      separated from it by white space.  _o_p_t_a_r_g is set to point to the start of
  34.      the option argument on return from _gggg_eeee_tttt_oooo_pppp_tttt.
  35.  
  36.      _gggg_eeee_tttt_oooo_pppp_tttt places in _o_p_t_i_n_d the _a_r_g_v index of the next argument to be
  37.      processed.  _o_p_t_i_n_d is external and is initialized to 1 before the first
  38.      call to _gggg_eeee_tttt_oooo_pppp_tttt.  When all options have been processed (i.e., up to the
  39.      first non-option argument), _gggg_eeee_tttt_oooo_pppp_tttt returns _----_1111.  The special option ``_----_----''
  40.      (two hyphens) may be used to delimit the end of the options; when it is
  41.      encountered, _----_1111 is returned and ``_----_----'' is skipped. This is useful in
  42.      delimiting non-option arguments that begin with ``_----'' (hyphen).
  43.  
  44.      _gggg_eeee_tttt_oooo_pppp_tttt_rrrr_eeee_ssss_eeee_tttt can be used to reset all the internal state of _gggg_eeee_tttt_oooo_pppp_tttt so that
  45.      it may be used again on a different set of arguments.
  46.  
  47. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  48.      The following code fragment shows how one might process the arguments for
  49.      a command that can take the mutually exclusive options _aaaa and _bbbb, and the
  50.      option _oooo, which requires an argument:
  51.  
  52.      #include <unistd.h>
  53.  
  54.      main (int argc, char *argv[])
  55.      {
  56.           int c;
  57.           extern char *optarg;
  58.           extern int optind;
  59.           int aflg = 0;
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ggggeeeettttoooopppptttt((((3333CCCC))))                                                          ggggeeeettttoooopppptttt((((3333CCCC))))
  71.  
  72.  
  73.  
  74.          int bflg = 0;
  75.           int errflg = 0;
  76.           char *ofile = NULL;
  77.  
  78.           while ((c = getopt(argc, argv, "abo:")) != -1)
  79.                switch (c) {
  80.                case 'a':
  81.                     if (bflg)
  82.                          errflg++;
  83.                     else
  84.                          aflg++;
  85.                     break;
  86.                case 'b':
  87.                     if (aflg)
  88.                          errflg++;
  89.                     else
  90.                          bflg++;
  91.                     break;
  92.                case 'o':
  93.                     ofile = optarg;
  94.                     (void)printf("ofile = %s\n", ofile);
  95.                     break;
  96.                case '?':
  97.                     errflg++;
  98.                }
  99.           if (errflg) {
  100.                (void)fprintf(stderr,
  101.                     "usage: cmd [-a|-b] [-o<file>] files...\n");
  102.                exit (2);
  103.           }
  104.           for ( ; optind < argc; optind++)
  105.                (void)printf("%s\n", argv[optind]);
  106.           return 0;
  107.      }
  108.  
  109. FFFFIIIILLLLEEEESSSS
  110.      _////_uuuu_ssss_rrrr_////_llll_iiii_bbbb_////_llll_oooo_cccc_aaaa_llll_eeee_////_l_o_c_a_l_e_////_LLLL_CCCC______MMMM_EEEE_SSSS_SSSS_AAAA_GGGG_EEEE_SSSS_////_uuuu_xxxx_llll_iiii_bbbb_cccc
  111.           language-specific message file [See _LLLL_AAAA_NNNN_GGGG on _eeee_nnnn_vvvv_iiii_rrrr_oooo_nnnn(5).]
  112.  
  113. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  114.      _gggg_eeee_tttt_oooo_pppp_tttt_ssss(1), _iiii_nnnn_tttt_rrrr_oooo(1), _gggg_eeee_tttt_ssss_uuuu_bbbb_oooo_pppp_tttt(3C), _pppp_ffff_mmmm_tttt(3C), _ssss_eeee_tttt_llll_aaaa_bbbb_eeee_llll(3C)
  115.  
  116. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  117.      The _gggg_eeee_tttt_oooo_pppp_tttt function returns the next option character specified on the
  118.      command line.
  119.  
  120.      A colon character ``_::::''  is returned if _gggg_eeee_tttt_oooo_pppp_tttt detects a missing argument
  121.      and the first character of _o_p_t_s_t_r_i_n_g was a colon character ``_::::''.
  122.  
  123.      A question mark character ``_????''  is returned if _gggg_eeee_tttt_oooo_pppp_tttt encounters an
  124.      option character not in _o_p_t_s_t_r_i_n_g or detects a missing argument and the
  125.      first character of _o_p_t_s_t_r_i_n_g was not a colon character ``_::::''.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ggggeeeettttoooopppptttt((((3333CCCC))))                                                          ggggeeeettttoooopppptttt((((3333CCCC))))
  137.  
  138.  
  139.  
  140.      Otherwise _gggg_eeee_tttt_oooo_pppp_tttt returns _----_1111 when all command line options are parsed.
  141.  
  142. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  143.      If _gggg_eeee_tttt_oooo_pppp_tttt detects a missing option-argument, it returns the ``_::::''  colon
  144.      character if the first character of _o_p_t_s_t_r_i_n_g was a colon, or a ``_????''
  145.      (question mark) character otherwise.  If the application has not set the
  146.      variable _oooo_pppp_tttt_eeee_rrrr_rrrr to zero and the first character of _o_p_t_s_t_r_i_n_g is not a
  147.      colon, _gggg_eeee_tttt_oooo_pppp_tttt also prints a diagnostic message in the standard error
  148.      format.  The value of the character that caused the error is in _oooo_pppp_tttt_oooo_pppp_tttt.
  149.  
  150.      The label defined by a call to _ssss_eeee_tttt_llll_aaaa_bbbb_eeee_llll(3C) will be used if available;
  151.      otherwise the name of the utility (_aaaa_rrrr_gggg_vvvv_[[[[_0000_]]]]) will be used.  Remember to
  152.      set the environment variable (_NNNN_OOOO_MMMM_SSSS_GGGG_SSSS_EEEE_VVVV_EEEE_RRRR_IIII_TTTT_YYYY_====_1111) for X/Open conformance.
  153.      Also, the environment variable (_NNNN_OOOO_MMMM_SSSS_GGGG_LLLL_AAAA_BBBB_EEEE_LLLL) must be not defined in order
  154.      for _ssss_eeee_tttt_llll_aaaa_bbbb_eeee_llll(3C) to print labels.
  155.  
  156. NNNNOOOOTTTTEEEESSSS
  157.      The library routine _gggg_eeee_tttt_oooo_pppp_tttt does not fully check for mandatory arguments.
  158.      That is, given an option string _aaaa_::::_bbbb and the input _----_aaaa _----_bbbb, _gggg_eeee_tttt_oooo_pppp_tttt assumes
  159.      that _----_bbbb is the mandatory argument to the option _----_aaaa and not that _----_aaaa is
  160.      missing a mandatory argument.
  161.  
  162.      It is a violation of the command syntax standard [see _iiii_nnnn_tttt_rrrr_oooo(1)] for
  163.      options with arguments to be grouped with other options, as in _cccc_mmmm_dddd
  164.      _----_aaaa_bbbb_oooo_xxxx_xxxx_xxxx _ffff_iiii_llll_eeee, where _aaaa and _bbbb are options, _oooo is an option that requires an
  165.      argument, and _xxxx_xxxx_xxxx is the argument to _oooo.  Although this syntax is
  166.      permitted in the current implementation, it should not be used because it
  167.      may not be supported in future releases. The correct syntax is _cccc_mmmm_dddd _----_aaaa_bbbb _----_oooo
  168.      _xxxx_xxxx_xxxx _ffff_iiii_llll_eeee.
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.