logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

getsubopt.3p (7571B)

    

  1. '\" et
  2. .TH GETSUBOPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. getsubopt
  12. \(em parse suboption arguments from a string
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdlib.h>
  17. .P
  18. int getsubopt(char **\fIoptionp\fP, char * const *\fIkeylistp\fP, char **\fIvaluep\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIgetsubopt\fR()
  23. function shall parse suboption arguments in a flag argument. Such
  24. options often result from the use of
  25. \fIgetopt\fR().
  26. .P
  27. The
  28. \fIgetsubopt\fR()
  29. argument
  30. .IR optionp
  31. is a pointer to a pointer to the option argument string. The suboption
  32. arguments shall be separated by
  33. <comma>
  34. characters and each may consist of either a single token, or a token-value
  35. pair separated by an
  36. <equals-sign>.
  37. .P
  38. The
  39. .IR keylistp
  40. argument shall be a pointer to a vector of strings. The end of the
  41. vector is identified by a null pointer. Each entry in the vector is one
  42. of the possible tokens that might be found in *\fIoptionp\fP. Since
  43. <comma>
  44. characters delimit suboption arguments in
  45. .IR optionp ,
  46. they should not appear in any of the strings pointed to by
  47. .IR keylistp .
  48. Similarly, because an
  49. <equals-sign>
  50. separates a token from its value, the application should not include an
  51. <equals-sign>
  52. in any of the strings pointed to by
  53. .IR keylistp .
  54. The
  55. \fIgetsubopt\fR()
  56. function shall not modify the
  57. .IR keylistp
  58. vector.
  59. .P
  60. The
  61. .IR valuep
  62. argument is the address of a value string pointer.
  63. .P
  64. If a
  65. <comma>
  66. appears in
  67. .IR optionp ,
  68. it shall be interpreted as a suboption separator. After
  69. <comma>
  70. characters have been processed, if there are one or more
  71. <equals-sign>
  72. characters in a suboption string, the first
  73. <equals-sign>
  74. in any suboption string shall be interpreted as a separator between a
  75. token and a value. Subsequent
  76. <equals-sign>
  77. characters in a suboption string shall be interpreted as part of the
  78. value.
  79. .P
  80. If the string at *\fIoptionp\fP contains only one suboption argument
  81. (equivalently, no
  82. <comma>
  83. characters),
  84. \fIgetsubopt\fR()
  85. shall update *\fIoptionp\fP to point to the null character at the end of
  86. the string. Otherwise, it shall isolate the suboption argument by
  87. replacing the
  88. <comma>
  89. separator with a null character, and shall update *\fIoptionp\fP to point
  90. to the start of the next suboption argument. If the suboption argument
  91. has an associated value (equivalently, contains an
  92. <equals-sign>),
  93. \fIgetsubopt\fR()
  94. shall update *\fIvaluep\fP to point to the value's first character.
  95. Otherwise, it shall set *\fIvaluep\fP to a null pointer. The calling
  96. application may use this information to determine whether the presence
  97. or absence of a value for the suboption is an error.
  98. .P
  99. Additionally, when
  100. \fIgetsubopt\fR()
  101. fails to match the suboption argument with a token in the
  102. .IR keylistp
  103. array, the calling application should decide if this is an error, or if
  104. the unrecognized option should be processed in another way.
  105. .SH "RETURN VALUE"
  106. The
  107. \fIgetsubopt\fR()
  108. function shall return the index of the matched token string, or \-1
  109. if no token strings were matched.
  110. .SH ERRORS
  111. No errors are defined.
  112. .LP
  113. .IR "The following sections are informative."
  114. .SH EXAMPLES
  115. .SS "Parsing Suboptions"
  116. .P
  117. The following example uses the
  118. \fIgetsubopt\fR()
  119. function to parse a
  120. .IR value
  121. argument in the
  122. .IR optarg
  123. external variable returned by a call to
  124. \fIgetopt\fR().
  125. .sp
  126. .RS 4
  127. .nf
  129. #include <stdio.h>
  130. #include <stdlib.h>
  131. #include <unistd.h>
  132. .P
  133. int do_all;
  134. const char *type;
  135. int read_size;
  136. int write_size;
  137. int read_only;
  138. .P
  139. enum
  140. {
  141.     RO_OPTION = 0,
  142.     RW_OPTION,
  143.     READ_SIZE_OPTION,
  144.     WRITE_SIZE_OPTION
  145. };
  146. .P
  147. const char *mount_opts[] =
  148. {
  149.     [RO_OPTION] = "ro",
  150.     [RW_OPTION] = "rw",
  151.     [READ_SIZE_OPTION] = "rsize",
  152.     [WRITE_SIZE_OPTION] = "wsize",
  153.     NULL
  154. };
  155. .P
  156. int
  157. main(int argc, char *argv[])
  158. {
  159.     char *subopts, *value;
  160.     int opt;
  161. .P
  162.     while ((opt = getopt(argc, argv, "at:o:")) != -1)
  163.         switch(opt)
  164.             {
  165.             case \(aqa\(aq:
  166.                 do_all = 1;
  167.                 break;
  168.             case \(aqt\(aq:
  169.                 type = optarg;
  170.                 break;
  171.             case \(aqo\(aq:
  172.                 subopts = optarg;
  173.                 while (*subopts != \(aq\0\(aq)
  174.                 {
  175.                     char *saved = subopts;
  176.                     switch(getsubopt(&subopts, (char **)mount_opts,
  177.                         &value))
  178.                     {
  179.                     case RO_OPTION:
  180.                         read_only = 1;
  181.                         break;
  182.                     case RW_OPTION:
  183.                         read_only = 0;
  184.                         break;
  185.                     case READ_SIZE_OPTION:
  186.                         if (value == NULL)
  187.                             abort();
  188.                         read_size = atoi(value);
  189.                         break;
  190.                     case WRITE_SIZE_OPTION:
  191.                         if (value == NULL)
  192.                             abort();
  193.                         write_size = atoi(value);
  194.                         break;
  195.                     default:
  196.                         /* Unknown suboption. */
  197.                         printf("Unknown suboption `%s\(aq\en", saved);
  198.                         abort();
  199.                     }
  200.                 }
  201.                 break;
  202.             default:
  203.                 abort();
  204.             }
  205. .P
  206.     /* Do the real work. */
  207. .P
  208.     return 0;
  209. }
  210. .fi
  211. .P
  212. .RE
  213. .P
  214. If the above example is invoked with:
  215. .sp
  216. .RS 4
  217. .nf
  219. program -o ro,rsize=512
  220. .fi
  221. .P
  222. .RE
  223. .P
  224. then after option parsing, the variable
  225. .IR do_all
  226. will be 0,
  227. .IR type
  228. will be a null pointer,
  229. .IR read_size
  230. will be 512,
  231. .IR write_size
  232. will be 0, and
  233. .IR read_only
  234. will be 1. If it is invoked with:
  235. .sp
  236. .RS 4
  237. .nf
  239. program -o oops
  240. .fi
  241. .P
  242. .RE
  243. .P
  244. it will print:
  245. .sp
  246. .RS 4
  247. .nf
  249. "Unknown suboption `oops\(aq"
  250. .fi
  251. .P
  252. .RE
  253. .P
  254. before aborting.
  255. .SH "APPLICATION USAGE"
  256. The value of *\fIvaluep\fR when
  257. \fIgetsubopt\fR()
  258. returns \-1 is unspecified. Historical implementations provide various
  259. incompatible extensions to allow an application to access the suboption
  260. text that was not found in the
  261. .IR keylistp
  262. array.
  263. .SH RATIONALE
  264. The
  265. .IR keylistp
  266. argument of
  267. \fIgetsubopt\fR()
  268. is typed as
  269. .BR "char * const *"
  270. to match historical practice. However, the standard is clear that
  271. implementations will not modify either the array or the strings contained
  272. in the array, as if the argument had been typed
  273. .BR "const char * const *" .
  274. .SH "FUTURE DIRECTIONS"
  275. None.
  276. .SH "SEE ALSO"
  277. .IR "\fIgetopt\fR\^(\|)"
  278. .P
  279. The Base Definitions volume of POSIX.1\(hy2017,
  280. .IR "\fB<stdlib.h>\fP"
  281. .\"
  282. .SH COPYRIGHT
  283. Portions of this text are reprinted and reproduced in electronic form
  284. from IEEE Std 1003.1-2017, Standard for Information Technology
  285. -- Portable Operating System Interface (POSIX), The Open Group Base
  286. Specifications Issue 7, 2018 Edition,
  287. Copyright (C) 2018 by the Institute of
  288. Electrical and Electronics Engineers, Inc and The Open Group.
  289. In the event of any discrepancy between this version and the original IEEE and
  290. The Open Group Standard, the original IEEE and The Open Group Standard
  291. is the referee document. The original Standard can be obtained online at
  292. http://www.opengroup.org/unix/online.html .
  293. .PP
  294. Any typographical or formatting errors that appear
  295. in this page are most likely
  296. to have been introduced during the conversion of the source files to
  297. man page format. To report such errors, see
  298. https://www.kernel.org/doc/man-pages/reporting_bugs.html .