Warning, /education/cantor/thirdparty/discount-2.2.6-patched/gethopt.3 is written in an unsupported language. File is not indexed.
0001 .\" Copyright (c) 1988, 1991 Regents of the University of California. 0002 .\" Copyright (c) 2017 David Loren Parsons. 0003 .\" All rights reserved. 0004 .\" 0005 .\" Redistribution and use in source and binary forms, with or without 0006 .\" modification, are permitted provided that the following conditions 0007 .\" are met: 0008 .\" 1. Redistributions of source code must retain the above copyright 0009 .\" notice, this list of conditions and the following disclaimer. 0010 .\" 2. Redistributions in binary form must reproduce the above copyright 0011 .\" notice, this list of conditions and the following disclaimer in the 0012 .\" documentation and/or other materials provided with the distribution. 0013 .\" 3. All advertising materials mentioning features or use of this software 0014 .\" must display the following acknowledgement: 0015 .\" This product includes software developed by the University of 0016 .\" California, Berkeley and its contributors. 0017 .\" 4. Neither the name of the University nor the names of its contributors 0018 .\" may be used to endorse or promote products derived from this software 0019 .\" without specific prior written permission. 0020 .\" 0021 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 0022 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 0023 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 0024 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 0025 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 0026 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 0027 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 0028 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 0029 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 0030 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 0031 .\" SUCH DAMAGE. 0032 .\" 0033 .Dd Jan 23, 2017 0034 .Dt GETHOPT 3 0035 .Os Mastodon 0036 .Sh NAME 0037 .Nm gethopt 0038 .Nd get option letter or word from argv 0039 .Sh SYNOPSIS 0040 .Fd #include "gethopt.h" 0041 0042 .Bd -literal -compact 0043 struct h_opt { 0044 int option; 0045 char *optword; 0046 char optchar; 0047 int opthasarg; 0048 char *optdesc; 0049 } ; 0050 .Ed 0051 .Ft char* 0052 .Fn hoptarg "struct h_context* argctx" 0053 .Ft int 0054 .Fn hoptind "struct h_context* argctx" 0055 .Ft int 0056 .Fn hopterr "struct h_context* argctx" "int flag" 0057 .Ft char 0058 .Fn hoptopt "struct h_context* argctx" 0059 .Ft void 0060 .Fn hoptset "struct h_context* argctx" "int argc" "char** argv" 0061 .Ft struct h_opt* 0062 .Fn gethopt "struct h_context* argctx" "struct h_opt* optarray" "int nropts" 0063 0064 .Sh DESCRIPTION 0065 The 0066 .Fn gethopt 0067 function gets 0068 the next 0069 .Em known 0070 option word or character from 0071 .Fa argctx . 0072 An option is 0073 .Em known 0074 if it has been specified in the array of accepted options 0075 .Fa optarray . 0076 .Pp 0077 The option array 0078 .Fa optarray 0079 contains records with either an option word, character, or both, 0080 a flag saying the option needs an argument, a short description 0081 of the option, and an 0082 .Va option 0083 key (which is there for the convenience of the calling program; 0084 .Fn gethopt 0085 does not use it in any way.). 0086 It does not matter to 0087 .Fn getopt 0088 if a following argument has leading white space. 0089 .Pp 0090 On return from 0091 .Fn gethopt , 0092 .Fn hoptarg 0093 returns an option argument, if it is anticipated, 0094 and the variable 0095 .Fn hoptind 0096 contains the index to the next 0097 .Fa argv 0098 argument for a subsequent call 0099 to 0100 .Fn gethopt . 0101 .Pp 0102 .Fn 0103 gethopt 0104 uses a (semi) opaque data blob to hold the current state, which 0105 must be initialized by the 0106 .Fn hoptset 0107 function. 0108 .Pp 0109 The 0110 .Fn gethopt 0111 function 0112 returns 0113 .Dv HOPTERR 0114 if a non-recognized 0115 option is encountered, 0116 and NULL when it reaches the end of the options on the command line.. 0117 .Pp 0118 The interpretation of options in the argument list may be cancelled 0119 by 0120 .Ql - 0121 (single dash) or 0122 .Ql -- 0123 (double dash) which causes 0124 .Fn getopt 0125 to signal the end of argument processing and return an 0126 .Dv NULL . 0127 When all options have been processed (i.e., up to the first non-option 0128 argument), 0129 .Fn gethopt 0130 returns 0131 .Dv NULL . 0132 .Sh DIAGNOSTICS 0133 If the 0134 .Fn gethopt 0135 function encounters a character not found in 0136 .Va optarray 0137 or detects 0138 a missing option argument 0139 it returns 0140 .Dv HOPTERR 0141 (and writes an error message to the 0142 .Em stderr 0143 if 0144 .Fn hopterr 0145 is used to turn error reporting on.) 0146 .Sh EXAMPLE 0147 .Bd -literal -compact 0148 struct h_opt opts[] = { 0149 { 0, "css", 0, 1, "css file" }, 0150 { 1, "header", 0, 1, "header file" }, 0151 { 2, 0, 'a', 0, "option a (no arg)" }, 0152 { 3, 0, 'b', 1, "option B (with arg)" }, 0153 { 4, "help", '?', 0, "help message" }, 0154 } ; 0155 0156 #define NROPT (sizeof opts/sizeof opts[0]) 0157 0158 0159 int 0160 main(argc, argv) 0161 char **argv; 0162 { 0163 struct h_opt *ret; 0164 struct h_context ctx; 0165 0166 hoptset(&ctx, argc, argv); 0167 hopterr(&ctx, 1); 0168 0169 while (( ret = gethopt(&ctx, opts, NROPT) )) { 0170 0171 if ( ret != HOPTERR ) { 0172 if ( ret->optword ) 0173 printf("%s", ret->optword); 0174 else 0175 printf("%c", ret->optchar); 0176 0177 if ( ret->opthasarg ) { 0178 if ( hoptarg(&ctx) ) 0179 printf(" = %s", hoptarg(&ctx)); 0180 else 0181 printf(" with no argument?"); 0182 } 0183 puts(ret->optdesc ? ret->optdesc : ""); 0184 } 0185 } 0186 0187 argc -= hoptind(&ctx); 0188 argv += hoptind(&ctx); 0189 0190 .Ed 0191 .Sh HISTORY 0192 The 0193 .Fn gethopt 0194 function was a quick hack to replace manually parsing full-word arguments 0195 in 0196 .Va discount .