diff options
Diffstat (limited to 'upstream/archlinux/man3p/getsubopt.3p')
| -rw-r--r-- | upstream/archlinux/man3p/getsubopt.3p | 298 |
1 files changed, 298 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/getsubopt.3p b/upstream/archlinux/man3p/getsubopt.3p new file mode 100644 index 00000000..69a0a916 --- /dev/null +++ b/upstream/archlinux/man3p/getsubopt.3p @@ -0,0 +1,298 @@ +'\" et +.TH GETSUBOPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getsubopt +\(em parse suboption arguments from a string +.SH SYNOPSIS +.LP +.nf +#include <stdlib.h> +.P +int getsubopt(char **\fIoptionp\fP, char * const *\fIkeylistp\fP, char **\fIvaluep\fP); +.fi +.SH DESCRIPTION +The +\fIgetsubopt\fR() +function shall parse suboption arguments in a flag argument. Such +options often result from the use of +\fIgetopt\fR(). +.P +The +\fIgetsubopt\fR() +argument +.IR optionp +is a pointer to a pointer to the option argument string. The suboption +arguments shall be separated by +<comma> +characters and each may consist of either a single token, or a token-value +pair separated by an +<equals-sign>. +.P +The +.IR keylistp +argument shall be a pointer to a vector of strings. The end of the +vector is identified by a null pointer. Each entry in the vector is one +of the possible tokens that might be found in *\fIoptionp\fP. Since +<comma> +characters delimit suboption arguments in +.IR optionp , +they should not appear in any of the strings pointed to by +.IR keylistp . +Similarly, because an +<equals-sign> +separates a token from its value, the application should not include an +<equals-sign> +in any of the strings pointed to by +.IR keylistp . +The +\fIgetsubopt\fR() +function shall not modify the +.IR keylistp +vector. +.P +The +.IR valuep +argument is the address of a value string pointer. +.P +If a +<comma> +appears in +.IR optionp , +it shall be interpreted as a suboption separator. After +<comma> +characters have been processed, if there are one or more +<equals-sign> +characters in a suboption string, the first +<equals-sign> +in any suboption string shall be interpreted as a separator between a +token and a value. Subsequent +<equals-sign> +characters in a suboption string shall be interpreted as part of the +value. +.P +If the string at *\fIoptionp\fP contains only one suboption argument +(equivalently, no +<comma> +characters), +\fIgetsubopt\fR() +shall update *\fIoptionp\fP to point to the null character at the end of +the string. Otherwise, it shall isolate the suboption argument by +replacing the +<comma> +separator with a null character, and shall update *\fIoptionp\fP to point +to the start of the next suboption argument. If the suboption argument +has an associated value (equivalently, contains an +<equals-sign>), +\fIgetsubopt\fR() +shall update *\fIvaluep\fP to point to the value's first character. +Otherwise, it shall set *\fIvaluep\fP to a null pointer. The calling +application may use this information to determine whether the presence +or absence of a value for the suboption is an error. +.P +Additionally, when +\fIgetsubopt\fR() +fails to match the suboption argument with a token in the +.IR keylistp +array, the calling application should decide if this is an error, or if +the unrecognized option should be processed in another way. +.SH "RETURN VALUE" +The +\fIgetsubopt\fR() +function shall return the index of the matched token string, or \-1 +if no token strings were matched. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Parsing Suboptions" +.P +The following example uses the +\fIgetsubopt\fR() +function to parse a +.IR value +argument in the +.IR optarg +external variable returned by a call to +\fIgetopt\fR(). +.sp +.RS 4 +.nf + +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +.P +int do_all; +const char *type; +int read_size; +int write_size; +int read_only; +.P +enum +{ + RO_OPTION = 0, + RW_OPTION, + READ_SIZE_OPTION, + WRITE_SIZE_OPTION +}; +.P +const char *mount_opts[] = +{ + [RO_OPTION] = "ro", + [RW_OPTION] = "rw", + [READ_SIZE_OPTION] = "rsize", + [WRITE_SIZE_OPTION] = "wsize", + NULL +}; +.P +int +main(int argc, char *argv[]) +{ + char *subopts, *value; + int opt; +.P + while ((opt = getopt(argc, argv, "at:o:")) != -1) + switch(opt) + { + case \(aqa\(aq: + do_all = 1; + break; + case \(aqt\(aq: + type = optarg; + break; + case \(aqo\(aq: + subopts = optarg; + while (*subopts != \(aq\0\(aq) + { + char *saved = subopts; + switch(getsubopt(&subopts, (char **)mount_opts, + &value)) + { + case RO_OPTION: + read_only = 1; + break; + case RW_OPTION: + read_only = 0; + break; + case READ_SIZE_OPTION: + if (value == NULL) + abort(); + read_size = atoi(value); + break; + case WRITE_SIZE_OPTION: + if (value == NULL) + abort(); + write_size = atoi(value); + break; + default: + /* Unknown suboption. */ + printf("Unknown suboption `%s\(aq\en", saved); + abort(); + } + } + break; + default: + abort(); + } +.P + /* Do the real work. */ +.P + return 0; +} +.fi +.P +.RE +.P +If the above example is invoked with: +.sp +.RS 4 +.nf + +program -o ro,rsize=512 +.fi +.P +.RE +.P +then after option parsing, the variable +.IR do_all +will be 0, +.IR type +will be a null pointer, +.IR read_size +will be 512, +.IR write_size +will be 0, and +.IR read_only +will be 1. If it is invoked with: +.sp +.RS 4 +.nf + +program -o oops +.fi +.P +.RE +.P +it will print: +.sp +.RS 4 +.nf + +"Unknown suboption `oops\(aq" +.fi +.P +.RE +.P +before aborting. +.SH "APPLICATION USAGE" +The value of *\fIvaluep\fR when +\fIgetsubopt\fR() +returns \-1 is unspecified. Historical implementations provide various +incompatible extensions to allow an application to access the suboption +text that was not found in the +.IR keylistp +array. +.SH RATIONALE +The +.IR keylistp +argument of +\fIgetsubopt\fR() +is typed as +.BR "char * const *" +to match historical practice. However, the standard is clear that +implementations will not modify either the array or the strings contained +in the array, as if the argument had been typed +.BR "const char * const *" . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetopt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<stdlib.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |