freeswan/doc/manpage.d/ipsec_optionsfrom.3.html

   1 Content-type: text/html
   2
   3 <HTML><HEAD><TITLE>Manpage of IPSEC_OPTIONSFROM</TITLE>
   4 </HEAD><BODY>
   5 <H1>IPSEC_OPTIONSFROM</H1>
   6 Section: C Library Functions (3)<BR>Updated: 16 Oct 1998<BR><A HREF="#index">Index</A>
   7 <A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
   8
   9
  10 <A NAME="lbAB">&nbsp;</A>
  11 <H2>NAME</H2>
  12
  13 ipsec optionsfrom - read additional ``command-line'' options from file
  14 <A NAME="lbAC">&nbsp;</A>
  15 <H2>SYNOPSIS</H2>
  16
  17 <B>#include &lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
  18
  19 <P>
  20 <B>const char *optionsfrom(char *filename, int *argcp,</B>
  21
  22 <BR>
  23 &nbsp;
  24 <B>char ***argvp, int optind, FILE *errsto);</B>
  25
  26 <A NAME="lbAD">&nbsp;</A>
  27 <H2>DESCRIPTION</H2>
  28
  29 <I>Optionsfrom</I>
  30
  31 is called from within a
  32 <I><A HREF="getopt_long.3.html">getopt_long</A></I>(3)
  33
  34 scan,
  35 as the result of the appearance of an option (preferably
  36 <B>--optionsfrom</B>)
  37
  38 to insert additional ``command-line'' arguments
  39 into the scan immediately after
  40 the option.
  41 Typically this would be done to pick up options which are
  42 security-sensitive and should not be visible to
  43 <I><A HREF="ps.1.html">ps</A></I>(1)
  44
  45 and similar commands,
  46 and hence cannot be supplied as part
  47 of the actual command line or the environment.
  48 <P>
  49
  50 <I>Optionsfrom</I>
  51
  52 reads the additional arguments from the specified
  53 <I>filename</I>,
  54
  55 allocates a new argument vector to hold pointers to the existing
  56 arguments plus the new ones,
  57 and amends
  58 <I>argc</I>
  59
  60 and
  61 <I>argv</I>
  62
  63 (via the pointers
  64 <I>argcp</I>
  65
  66 and
  67 <I>argvp</I>,
  68
  69 which must point to the
  70 <I>argc</I>
  71
  72 and
  73 <I>argv</I>
  74
  75 being supplied to
  76 <I><A HREF="getopt_long.3.html">getopt_long</A></I>(3))
  77
  78 accordingly.
  79 <I>Optind</I>
  80
  81 must be the index, in the original argument vector,
  82 of the next argument.
  83 <P>
  84
  85 If
  86 <I>errsto</I>
  87
  88 is NULL,
  89 <I>optionsfrom</I>
  90
  91 returns NULL for success and
  92 a pointer to a string-literal error message for failure;
  93 see DIAGNOSTICS.
  94 If
  95 <I>errsto</I>
  96
  97 is non-NULL and an error occurs,
  98 <I>optionsfrom</I>
  99
 100 prints a suitable complaint onto the
 101 <I>errsto</I>
 102
 103 descriptor and invokes
 104 <I>exit</I>
 105
 106 with an exit status of 2;
 107 this is a convenience for cases where more sophisticated
 108 responses are not required.
 109 <P>
 110
 111 The text of existing arguments is not disturbed by
 112 <I>optionsfrom</I>,
 113
 114 so pointers to them and into them remain valid.
 115 <P>
 116
 117 The file of additional arguments is an ASCII text file.
 118 Lines consisting solely of white space,
 119 and lines beginning with
 120 <B>#</B>,
 121
 122 are comments and are ignored.
 123 Otherwise, a line which does not begin with
 124 <B>-</B>
 125
 126 is taken to be a single argument;
 127 if it both begins and ends with double-quote (&quot;),
 128 those quotes are stripped off (note, no other processing is done within
 129 the line!).
 130 A line beginning with
 131 <B>-</B>
 132
 133 is considered to contain multiple arguments separated by white space.
 134 <P>
 135
 136 Because
 137 <I>optionsfrom</I>
 138
 139 reads its entire file before the
 140 <I><A HREF="getopt_long.3.html">getopt_long</A></I>(3)
 141
 142 scan is resumed, an
 143 <I>optionsfrom</I>
 144
 145 file can contain another
 146 <B>--optionsfrom</B>
 147
 148 option.
 149 Obviously, infinite loops are possible here.
 150 If
 151 <I>errsto</I>
 152
 153 is non-NULL,
 154 <I>optionsfrom</I>
 155
 156 considers it an error to be called more than 100 times.
 157 If
 158 <I>errsto</I>
 159
 160 is NULL,
 161 loop detection is up to the caller
 162 (and the internal loop counter is zeroed out).
 163 <A NAME="lbAE">&nbsp;</A>
 164 <H2>EXAMPLE</H2>
 165
 166 A reasonable way to invoke
 167 <I>optionsfrom</I>
 168
 169 would be like so:
 170 <P>
 171
 172 <PRE>
 173 <B>#include &lt;<A HREF="file:/usr/include/getopt.h">getopt.h</A>&gt;
 174
 175 struct option opts[] = {
 176         /* ... */
 177         &quot;optionsfrom&quot;,  1,      NULL,   '+',
 178         /* ... */
 179 };
 180
 181 int
 182 main(argc, argv)
 183 int argc;
 184 char *argv[];
 185 {
 186         int opt;
 187         extern char *optarg;
 188         extern int optind;
 189
 190         while ((opt = getopt_long(argc, argv, &quot;&quot;, opts, NULL)) != EOF)
 191                 switch (opt) {
 192                 /* ... */
 193                 case '+':       /* optionsfrom */
 194                         optionsfrom(optarg, &amp;argc, &amp;argv, optind, stderr);
 195                         /* does not return on error */
 196                         break;
 197                 /* ... */
 198                 }
 199         /* ... */
 200 </B></PRE>
 201
 202 <A NAME="lbAF">&nbsp;</A>
 203 <H2>SEE ALSO</H2>
 204
 205 <A HREF="getopt_long.3.html">getopt_long</A>(3)
 206 <A NAME="lbAG">&nbsp;</A>
 207 <H2>DIAGNOSTICS</H2>
 208
 209 Errors in
 210 <I>optionsfrom</I>
 211
 212 are:
 213 unable to open file;
 214 attempt to allocate temporary storage for argument or
 215 argument vector failed;
 216 read error in file;
 217 line too long.
 218 <A NAME="lbAH">&nbsp;</A>
 219 <H2>HISTORY</H2>
 220
 221 Written for the FreeS/WAN project by Henry Spencer.
 222 <A NAME="lbAI">&nbsp;</A>
 223 <H2>BUGS</H2>
 224
 225 The double-quote convention is rather simplistic.
 226 <P>
 227
 228 Line length is currently limited to 1023 bytes,
 229 and there is no continuation convention.
 230 <P>
 231
 232 The restriction of error reports to literal strings
 233 (so that callers don't need to worry about freeing them or copying them)
 234 does limit the precision of error reporting.
 235 <P>
 236
 237 The error-reporting convention lends itself
 238 to slightly obscure code,
 239 because many readers will not think of NULL as signifying success.
 240 <P>
 241
 242 There is a certain element of unwarranted chumminess with
 243 the insides of
 244 <I><A HREF="getopt_long.3.html">getopt_long</A></I>(3)
 245
 246 here.
 247 No non-public interfaces are actually used, but
 248 <I>optionsfrom</I>
 249
 250 does rely on
 251 <I><A HREF="getopt_long.3.html">getopt_long</A></I>(3)
 252
 253 being well-behaved in certain ways that are not actually
 254 promised by the specs.
 255 <P>
 256
 257 <HR>
 258 <A NAME="index">&nbsp;</A><H2>Index</H2>
 259 <DL>
 260 <DT><A HREF="#lbAB">NAME</A><DD>
 261 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
 262 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
 263 <DT><A HREF="#lbAE">EXAMPLE</A><DD>
 264 <DT><A HREF="#lbAF">SEE ALSO</A><DD>
 265 <DT><A HREF="#lbAG">DIAGNOSTICS</A><DD>
 266 <DT><A HREF="#lbAH">HISTORY</A><DD>
 267 <DT><A HREF="#lbAI">BUGS</A><DD>
 268 </DL>
 269 <HR>
 270 This document was created by
 271 <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
 272 using the manual pages.<BR>
 273 Time: 05:09:32 GMT, June 19, 2001
 274 </BODY>
 275 </HTML>