getopt.h 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130
  1. /* SPDX-License-Identifier: GPL-2.0-only */
  2. /*
  3. * getopt.h - a simple getopt(3) implementation.
  4. *
  5. * Copyright (C) 2020 Sean Anderson <seanga2@gmail.com>
  6. * Copyright (c) 2007 Sascha Hauer <s.hauer@pengutronix.de>, Pengutronix
  7. */
  8. #ifndef __GETOPT_H
  9. #define __GETOPT_H
  10. /**
  11. * struct getopt_state - Saved state across getopt() calls
  12. */
  13. struct getopt_state {
  14. /**
  15. * @index: Index of the next unparsed argument of @argv. If getopt() has
  16. * parsed all of @argv, then @index will equal @argc.
  17. */
  18. int index;
  19. /* private: */
  20. /** @arg_index: Index within the current argument */
  21. int arg_index;
  22. union {
  23. /* public: */
  24. /**
  25. * @opt: Option being parsed when an error occurs. @opt is only
  26. * valid when getopt() returns ``?`` or ``:``.
  27. */
  28. int opt;
  29. /**
  30. * @arg: The argument to an option, NULL if there is none. @arg
  31. * is only valid when getopt() returns an option character.
  32. */
  33. char *arg;
  34. /* private: */
  35. };
  36. };
  37. /**
  38. * getopt_init_state() - Initialize a &struct getopt_state
  39. * @gs: The state to initialize
  40. *
  41. * This must be called before using @gs with getopt().
  42. */
  43. void getopt_init_state(struct getopt_state *gs);
  44. int __getopt(struct getopt_state *gs, int argc, char *const argv[],
  45. const char *optstring, bool silent);
  46. /**
  47. * getopt() - Parse short command-line options
  48. * @gs: Internal state and out-of-band return arguments. This must be
  49. * initialized with getopt_init_context() beforehand.
  50. * @argc: Number of arguments, not including the %NULL terminator
  51. * @argv: Argument list, terminated by %NULL
  52. * @optstring: Option specification, as described below
  53. *
  54. * getopt() parses short options. Short options are single characters. They may
  55. * be followed by a required argument or an optional argument. Arguments to
  56. * options may occur in the same argument as an option (like ``-larg``), or
  57. * in the following argument (like ``-l arg``). An argument containing
  58. * options begins with a ``-``. If an option expects no arguments, then it may
  59. * be immediately followed by another option (like ``ls -alR``).
  60. *
  61. * @optstring is a list of accepted options. If an option is followed by ``:``
  62. * in @optstring, then it expects a mandatory argument. If an option is followed
  63. * by ``::`` in @optstring, it expects an optional argument. @gs.arg points
  64. * to the argument, if one is parsed.
  65. *
  66. * getopt() stops parsing options when it encounters the first non-option
  67. * argument, when it encounters the argument ``--``, or when it runs out of
  68. * arguments. For example, in ``ls -l foo -R``, option parsing will stop when
  69. * getopt() encounters ``foo``, if ``l`` does not expect an argument. However,
  70. * the whole list of arguments would be parsed if ``l`` expects an argument.
  71. *
  72. * An example invocation of getopt() might look like::
  73. *
  74. * char *argv[] = { "program", "-cbx", "-a", "foo", "bar", 0 };
  75. * int opt, argc = ARRAY_SIZE(argv) - 1;
  76. * struct getopt_state gs;
  77. *
  78. * getopt_init_state(&gs);
  79. * while ((opt = getopt(&gs, argc, argv, "a::b:c")) != -1)
  80. * printf("opt = %c, index = %d, arg = \"%s\"\n", opt, gs.index, gs.arg);
  81. * printf("%d argument(s) left\n", argc - gs.index);
  82. *
  83. * and would produce an output of::
  84. *
  85. * opt = c, index = 1, arg = "<NULL>"
  86. * opt = b, index = 2, arg = "x"
  87. * opt = a, index = 4, arg = "foo"
  88. * 1 argument(s) left
  89. *
  90. * For further information, refer to the getopt(3) man page.
  91. *
  92. * Return:
  93. * * An option character if an option is found. @gs.arg is set to the
  94. * argument if there is one, otherwise it is set to ``NULL``.
  95. * * ``-1`` if there are no more options, if a non-option argument is
  96. * encountered, or if an ``--`` argument is encountered.
  97. * * ``'?'`` if we encounter an option not in @optstring. @gs.opt is set to
  98. * the unknown option.
  99. * * ``':'`` if an argument is required, but no argument follows the
  100. * option. @gs.opt is set to the option missing its argument.
  101. *
  102. * @gs.index is always set to the index of the next unparsed argument in @argv.
  103. */
  104. static inline int getopt(struct getopt_state *gs, int argc,
  105. char *const argv[], const char *optstring)
  106. {
  107. return __getopt(gs, argc, argv, optstring, false);
  108. }
  109. /**
  110. * getopt_silent() - Parse short command-line options silently
  111. * @gs: State
  112. * @argc: Argument count
  113. * @argv: Argument list
  114. * @optstring: Option specification
  115. *
  116. * Same as getopt(), except no error messages are printed.
  117. */
  118. static inline int getopt_silent(struct getopt_state *gs, int argc,
  119. char *const argv[], const char *optstring)
  120. {
  121. return __getopt(gs, argc, argv, optstring, true);
  122. }
  123. #endif /* __GETOPT_H */