2007-09-20 06:52:22 +00:00
|
|
|
.\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
|
2008-07-08 14:21:20 +00:00
|
|
|
.\" and Copyright (C) 2007 Justin Pryzby <pryzbyj@justinpryzby.com>
|
2007-05-04 22:21:25 +00:00
|
|
|
.\"
|
|
|
|
.\" 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.
|
|
|
|
.\"
|
_exit.2, brk.2, capget.2, chdir.2, chmod.2, chown.2, chroot.2, getdtablesize.2, gethostname.2, getpagesize.2, getsid.2, killpg.2, mknod.2, mknodat.2, poll.2, posix_fadvise.2, pread.2, readlink.2, setpgid.2, setreuid.2, sigaltstack.2, stat.2, symlink.2, sync.2, truncate.2, vfork.2, wait.2, wait4.2, a64l.3, abs.3, acos.3, acosh.3, asin.3, asinh.3, atan.3, atan2.3, atoi.3, cbrt.3, ceil.3, copysign.3, cosh.3, dirfd.3, div.3, ecvt.3, erf.3, erfc.3, exp.3, exp2.3, fabs.3, fdim.3, ffs.3, floor.3, fma.3, fmax.3, fmin.3, fmod.3, fpclassify.3, frexp.3, ftw.3, fwide.3, gcvt.3, getcwd.3, getdate.3, getgrent.3, gethostid.3, getpass.3, getpwent.3, getsubopt.3, getw.3, hypot.3, ilogb.3, index.3, isalpha.3, isgreater.3, iswblank.3, j0.3, ldexp.3, lockf.3, log.3, log10.3, log1p.3, logb.3, lrint.3, lround.3, mkstemp.3, mktemp.3, modf.3, mq_receive.3, mq_send.3, nan.3, nextafter.3, posix_fallocate.3, posix_memalign.3, printf.3, qecvt.3, random.3, realpath.3, remainder.3, remquo.3, rint.3, round.3, scalb.3, scalbln.3, scanf.3, siginterrupt.3, signbit.3, sigset.3, sinh.3, sqrt.3, strcasecmp.3, strcat.3, strchr.3, strcmp.3, strcoll.3, strcpy.3, strfry.3, strpbrk.3, strsep.3, strspn.3, strstr.3, strtod.3, strtok.3, strtol.3, strtoul.3, strxfrm.3, tanh.3, tgamma.3, trunc.3, ttyslot.3, ualarm.3, usleep.3, wprintf.3, armscii-8.7, cp1251.7, iso_8859-10.7, iso_8859-11.7, iso_8859-13.7, iso_8859-14.7, iso_8859-3.7, iso_8859-5.7, iso_8859-6.7, iso_8859-8.7, koi8-u.7: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-09-19 17:19:13 +00:00
|
|
|
.TH GETSUBOPT 3 2010-09-20 "GNU" "Linux Programmer's Manual"
|
2007-05-04 22:21:25 +00:00
|
|
|
.SH NAME
|
|
|
|
getsubopt \- parse suboption arguments from a string
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.B #include <stdlib.h>
|
|
|
|
|
2008-05-06 07:47:45 +00:00
|
|
|
.BI "int getsubopt(char **"optionp ", char * const *" tokens \
|
|
|
|
", char **" valuep );
|
2010-09-17 16:01:30 +00:00
|
|
|
.sp
|
|
|
|
.in -4n
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
|
|
.BR feature_test_macros (7)):
|
|
|
|
.in
|
|
|
|
.sp
|
|
|
|
.BR getsubopt ():
|
|
|
|
.ad l
|
|
|
|
.RS 4
|
2010-09-18 08:29:58 +00:00
|
|
|
.PD 0
|
2010-09-17 16:01:30 +00:00
|
|
|
.TP 4
|
|
|
|
Since glibc 2.12
|
2010-09-19 05:21:43 +00:00
|
|
|
_XOPEN_SOURCE\ >= 500 ||
|
|
|
|
_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED ||
|
|
|
|
_POSIX_C_SOURCE\ >=\ 200809L || _XOPEN_SOURCE\ >=\ 700
|
2010-09-17 16:01:30 +00:00
|
|
|
.TP
|
|
|
|
Before glibc 2.12
|
brk.2, chroot.2, faccessat.2, fchmodat.2, fchownat.2, fstatat.2, futimesat.2, getdtablesize.2, getpagesize.2, getsid.2, linkat.2, mkdirat.2, mknodat.2, openat.2, pread.2, readlinkat.2, renameat.2, setpgid.2, sigaltstack.2, symlinkat.2, sync.2, timer_create.2, timer_delete.2, timer_getoverrun.2, timer_settime.2, unlinkat.2, utimensat.2, vfork.2, acosh.3, asinh.3, atanh.3, dirfd.3, dprintf.3, ecvt.3, expm1.3, fexecve.3, fmemopen.3, gcvt.3, getcwd.3, gethostid.3, getpass.3, getsubopt.3, getw.3, mbsnrtowcs.3, mkfifoat.3, mkstemp.3, mktemp.3, opendir.3, posix_memalign.3, rint.3, siginterrupt.3, stpcpy.3, stpncpy.3, strdup.3, strerror.3, strnlen.3, strsignal.3, strtol.3, strtoul.3, ualarm.3, usleep.3, wcpcpy.3, wcpncpy.3, wcscasecmp.3, wcsdup.3, wcsncasecmp.3, wcsnlen.3, wcsnrtombs.3: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-09-19 06:02:38 +00:00
|
|
|
_XOPEN_SOURCE\ >=\ 500 || _XOPEN_SOURCE\ &&' _XOPEN_SOURCE_EXTENDED
|
2010-09-18 08:29:58 +00:00
|
|
|
.PD
|
2010-09-17 16:01:30 +00:00
|
|
|
.RE
|
|
|
|
.ad
|
2007-05-04 22:21:25 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
.BR getsubopt ()
|
|
|
|
parses the list of comma-separated suboptions provided in
|
|
|
|
.IR optionp .
|
2007-06-21 22:55:04 +00:00
|
|
|
(Such a suboption list is typically produced when
|
2007-05-04 22:21:25 +00:00
|
|
|
.BR getopt (3)
|
|
|
|
is used to parse a command line;
|
2007-05-04 22:35:31 +00:00
|
|
|
see for example the \fI-o\fP option of
|
2007-05-04 22:21:25 +00:00
|
|
|
.BR mount (8).)
|
|
|
|
Each suboption may include an associated value,
|
|
|
|
which is separated from the suboption name by an equal sign.
|
2007-06-21 22:55:04 +00:00
|
|
|
The following is an example of the kind of string
|
|
|
|
that might be passed in
|
2007-05-04 22:21:25 +00:00
|
|
|
.IR optionp :
|
|
|
|
.sp
|
2007-12-19 07:19:23 +00:00
|
|
|
.in +4n
|
2007-05-04 22:21:25 +00:00
|
|
|
.B ro,name=xyz
|
2007-12-19 07:19:23 +00:00
|
|
|
.in
|
2007-05-04 22:21:25 +00:00
|
|
|
|
2007-06-21 22:55:04 +00:00
|
|
|
The
|
2007-05-04 22:21:25 +00:00
|
|
|
.I tokens
|
2007-05-27 16:26:54 +00:00
|
|
|
argument is a pointer to a NULL-terminated list of the tokens that
|
2007-05-12 00:30:29 +00:00
|
|
|
.BR getsubopt ()
|
2007-06-21 22:55:04 +00:00
|
|
|
will look for in
|
2007-05-04 22:21:25 +00:00
|
|
|
.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
|
2007-12-22 22:10:40 +00:00
|
|
|
.I *valuep
|
2007-05-04 22:21:25 +00:00
|
|
|
to the address of that string.
|
|
|
|
The first comma in
|
|
|
|
.I optionp
|
|
|
|
is overwritten with a null byte, so
|
2007-12-22 22:10:40 +00:00
|
|
|
.I *valuep
|
2007-05-04 22:21:25 +00:00
|
|
|
is precisely the "value string" for that suboption.
|
|
|
|
|
2007-06-08 09:56:56 +00:00
|
|
|
If the suboption is recognized, but no value string was found,
|
2007-12-22 22:10:40 +00:00
|
|
|
.I *valuep
|
2007-05-04 22:21:25 +00:00
|
|
|
is set to NULL.
|
|
|
|
|
|
|
|
When
|
|
|
|
.BR getsubopt ()
|
|
|
|
returns,
|
|
|
|
.I optionp
|
2010-08-29 06:57:21 +00:00
|
|
|
points to the next suboption,
|
|
|
|
or to the null byte ('\\0') at the end of the
|
2007-05-04 22:21:25 +00:00
|
|
|
string if the last suboption was just processed.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
If the first suboption in
|
|
|
|
.I optionp
|
2007-06-08 09:56:56 +00:00
|
|
|
is recognized,
|
2007-05-04 22:21:25 +00:00
|
|
|
.BR getsubopt ()
|
|
|
|
returns the index of the matching suboption element in
|
2007-11-18 07:28:32 +00:00
|
|
|
.IR tokens .
|
2007-05-04 22:21:25 +00:00
|
|
|
Otherwise, \-1 is returned and
|
2007-12-22 22:10:40 +00:00
|
|
|
.I *valuep
|
2007-05-04 22:21:25 +00:00
|
|
|
is the entire
|
|
|
|
.IB name [= value ]
|
|
|
|
string.
|
|
|
|
|
|
|
|
Since
|
2007-12-22 22:10:40 +00:00
|
|
|
.I *optionp
|
2007-05-04 22:21:25 +00:00
|
|
|
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
|
2007-12-22 22:10:40 +00:00
|
|
|
.IR *optionp ,
|
2007-05-04 22:21:25 +00:00
|
|
|
that string must be writable; it cannot be a string constant.
|
2007-05-16 17:35:34 +00:00
|
|
|
.SH EXAMPLE
|
2007-11-17 04:27:41 +00:00
|
|
|
The following program expects suboptions following a "\-o" option.
|
2007-05-04 22:21:25 +00:00
|
|
|
|
|
|
|
.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;
|
|
|
|
|
2007-06-20 21:39:45 +00:00
|
|
|
while ((opt = getopt(argc, argv, "o:")) != \-1) {
|
2007-06-20 20:52:14 +00:00
|
|
|
switch (opt) {
|
2008-06-09 15:49:35 +00:00
|
|
|
case \(aqo\(aq:
|
2007-05-04 22:21:25 +00:00
|
|
|
subopts = optarg;
|
2008-06-09 15:49:35 +00:00
|
|
|
while (*subopts != \(aq\\0\(aq && !errfnd) {
|
2007-05-04 22:21:25 +00:00
|
|
|
|
|
|
|
switch (getsubopt(&subopts, token, &value)) {
|
2007-06-22 04:59:15 +00:00
|
|
|
case RO_OPT:
|
|
|
|
readonly = 1;
|
|
|
|
break;
|
|
|
|
|
|
|
|
case RW_OPT:
|
|
|
|
readwrite = 1;
|
|
|
|
break;
|
|
|
|
|
|
|
|
case NAME_OPT:
|
|
|
|
if (value == NULL) {
|
|
|
|
fprintf(stderr, "Missing value for "
|
2008-06-09 15:49:35 +00:00
|
|
|
"suboption \(aq%s\(aq\\n", token[NAME_OPT]);
|
2007-05-04 22:21:25 +00:00
|
|
|
errfnd = 1;
|
2007-06-22 04:59:15 +00:00
|
|
|
continue;
|
2007-05-04 22:21:25 +00:00
|
|
|
}
|
2007-06-22 04:59:15 +00:00
|
|
|
|
|
|
|
name = value;
|
|
|
|
break;
|
|
|
|
|
|
|
|
default:
|
|
|
|
fprintf(stderr, "No match found "
|
|
|
|
"for token: /%s/\\n", value);
|
2007-05-04 22:21:25 +00:00
|
|
|
errfnd = 1;
|
2007-06-22 04:59:15 +00:00
|
|
|
break;
|
2007-05-04 22:21:25 +00:00
|
|
|
}
|
2007-06-22 04:59:15 +00:00
|
|
|
}
|
|
|
|
if (readwrite && readonly) {
|
2008-06-09 15:49:35 +00:00
|
|
|
fprintf(stderr, "Only one of \(aq%s\(aq and \(aq%s\(aq can be "
|
2007-06-22 04:59:15 +00:00
|
|
|
"specified\\n", token[RO_OPT], token[RW_OPT]);
|
|
|
|
errfnd = 1;
|
|
|
|
}
|
|
|
|
break;
|
2007-05-04 22:21:25 +00:00
|
|
|
|
|
|
|
default:
|
|
|
|
errfnd = 1;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
if (errfnd || argc == 1) {
|
2007-06-20 21:39:45 +00:00
|
|
|
fprintf(stderr, "\\nUsage: %s \-o <suboptstring>\\n", argv[0]);
|
2008-06-09 15:49:35 +00:00
|
|
|
fprintf(stderr, "suboptions are \(aqro\(aq, \(aqrw\(aq, "
|
|
|
|
"and \(aqname=<value>\(aq\\n");
|
2007-05-04 22:21:25 +00:00
|
|
|
exit(EXIT_FAILURE);
|
|
|
|
}
|
|
|
|
|
|
|
|
/* Remainder of program... */
|
|
|
|
|
|
|
|
exit(EXIT_SUCCESS);
|
|
|
|
}
|
|
|
|
.fi
|
|
|
|
.SH SEE ALSO
|
|
|
|
.BR getopt (3),
|
|
|
|
.BR feature_test_macros (7)
|