mirror of https://github.com/mkerrisk/man-pages
Doc for getsubopt().
This commit is contained in:
parent
bf9cf7db9d
commit
645259f435
|
@ -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)
|
Loading…
Reference in New Issue