diff options
| author | Michael Kerrisk <mtk.manpages@gmail.com> | 2007-05-04 22:21:25 +0000 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2007-05-04 22:21:25 +0000 |
| commit | 645259f4357baa3b3931ae24c79648baa155ebdf (patch) | |
| tree | 2be59b78e288e0a45b76c324d29ccabbc0fe708d | |
| parent | bf9cf7db9d2ad427ea77a9da3bbee81930a3a80b (diff) | |
| download | man-pages-645259f4357baa3b3931ae24c79648baa155ebdf.tar.gz | |
Doc for getsubopt().
| -rw-r--r-- | man3/getsubopt.3 | 215 |
1 files changed, 215 insertions, 0 deletions
diff --git a/man3/getsubopt.3 b/man3/getsubopt.3 new file mode 100644 index 0000000000..103d539d10 --- /dev/null +++ b/man3/getsubopt.3 @@ -0,0 +1,215 @@ +.\" Copyright (C) 2007 Michael Kerrisk <mtk-manpages@gmx.net> +.\" and (C) 2007 Justin Pryzby <pryzbyj@justinpryzby.com> +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be +.\" included in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +.\" +.TH GETSUBOPT 3 "2007-05-05" GNU +.SH NAME +getsubopt \- parse suboption arguments from a string +.SH SYNOPSIS +.B #define _XOPEN_SOURCE 500 +.br +.B #include <stdlib.h> + +.B int getsubopt(char +.BI ** optionp , +.B char *const +.BI * tokens , +.B char +.IB valuep ); +.SH DESCRIPTION +.BR getsubopt () +parses the list of comma-separated suboptions provided in +.IR optionp . +(Such a suboption list is typically produced when +.BR getopt (3) +is used to parse a command line; +see for example the \fI-o\fP of +.BR mount (8).) +Each suboption may include an associated value, +which is separated from the suboption name by an equal sign. +The following is an example of the kind of string +that might be passed in +.IR optionp : +.sp +.RS +.B ro,name=xyz +.RE + +The +.I tokens +argument is pointer to a NULL-terminated list of the tokens that +.BR getsupobts () +will look for in +.IR optionp . +The tokens should be distinct, null-terminated strings containing at +least one character, with no embedded equal signs or commas. + +Each call to +.BR getsubopt () +returns information about the next unprocessed suboption in +.IR optionp . +The first equal sign in a suboption (if any) is interpreted as a +separator between the name and the value of that suboption. +The value extends to the next comma, +or (for the last suboption) to the end of the string. +If the name of the suboption matches a known name from +.IR tokens , +and a value string was found, +.BR getsubopt () +sets +.RI * valuep +to the address of that string. +The first comma in +.I optionp +is overwritten with a null byte, so +.RI * valuep +is precisely the "value string" for that suboption. + +If the suboption is recognised, but no value string was found, +.RI * valuep +is set to NULL. + +When +.BR getsubopt () +returns, +.I optionp +points to the next suboption, or to the null character at the end of the +string if the last suboption was just processed. +.SH RETURN VALUE +If the first suboption in +.I optionp +is recognised, +.BR getsubopt () +returns the index of the matching suboption element in +.I tokens . +Otherwise, \-1 is returned and +.RI * valuep +is the entire +.IB name [= value ] +string. + +Since +.RI * optionp +is changed, the first suboption before the call to +.BR getsubopt () +is not (necessarily) the same as the first suboption after +.BR getsubopt (). +.SH CONFORMING TO +POSIX.1-2001. +.SH NOTES + +Since +.BR getsubopt () +overwrites any commas it finds in the string +.RI * optionp , +that string must be writable; it cannot be a string constant. +.SH EXAMPLE PROGRAM +The following program excepts suboptions following a "-o" option. + +.nf +#define _XOPEN_SOURCE 500 +#include <stdlib.h> +#include <assert.h> +#include <stdio.h> + +int main(int argc, char **argv) +{ + enum { + RO_OPT = 0, + RW_OPT, + NAME_OPT + }; + char *const token[] = { + [RO_OPT] = "ro", + [RW_OPT] = "rw", + [NAME_OPT] = "name", + NULL + }; + char *subopts; + char *value; + int opt; + + int readonly = 0; + int readwrite = 0; + char *name = NULL; + int errfnd = 0; + + while ((opt = getopt(argc, argv, "o:")) != -1) { + switch(opt) { + case 'o': + subopts = optarg; + while (*subopts != '\\0' && !errfnd) { + + switch (getsubopt(&subopts, token, &value)) { + case RO_OPT: + readonly = 1; + break; + + case RW_OPT: + readwrite = 1; + break; + + case NAME_OPT: + if (value == NULL) { + fprintf(stderr, "Missing value for " + "suboption '%s'\\n", token[NAME_OPT]); + errfnd = 1; + continue; + } + + name = value; + break; + + default: + fprintf(stderr, "No match found " + "for token: /%s/\\n", value); + errfnd = 1; + break; + } + } + if (readwrite && readonly) { + fprintf(stderr, "Only one of '%s' and '%s' can be " + "specified\\n", token[RO_OPT], token[RW_OPT]); + errfnd = 1; + } + break; + + default: + errfnd = 1; + } + } + + if (errfnd || argc == 1) { + fprintf(stderr, "\\nUsage: %s -o <suboptstring>\\n", argv[0]); + fprintf(stderr, "suboptions are 'ro', 'rw', " + "and 'name=<value>'\\n"); + exit(EXIT_FAILURE); + } + + /* Remainder of program... */ + + exit(EXIT_SUCCESS); +} +.fi +.SH SEE ALSO +.BR mount (1), +.BR getopt (3), +.BR feature_test_macros (7) |