freeswan/lib/optionsfrom.3

   1 .TH IPSEC_OPTIONSFROM 3 "16 Oct 1998"
   2 .\" RCSID $Id: optionsfrom.3,v 1.7 1999/04/05 21:30:34 henry Exp $
   3 .SH NAME
   4 ipsec optionsfrom \- read additional ``command-line'' options from file
   5 .SH SYNOPSIS
   6 .B "#include <freeswan.h>
   7 .sp
   8 .B "const char *optionsfrom(char *filename, int *argcp,"
   9 .ti +1c
  10 .B "char ***argvp, int optind, FILE *errsto);"
  11 .SH DESCRIPTION
  12 .I Optionsfrom
  13 is called from within a
  14 .IR getopt_long (3)
  15 scan,
  16 as the result of the appearance of an option (preferably
  17 .BR \-\-optionsfrom )
  18 to insert additional ``command-line'' arguments
  19 into the scan immediately after
  20 the option.
  21 Typically this would be done to pick up options which are
  22 security-sensitive and should not be visible to
  23 .IR ps (1)
  24 and similar commands,
  25 and hence cannot be supplied as part
  26 of the actual command line or the environment.
  27 .PP
  28 .I Optionsfrom
  29 reads the additional arguments from the specified
  30 .IR filename ,
  31 allocates a new argument vector to hold pointers to the existing
  32 arguments plus the new ones,
  33 and amends
  34 .I argc
  35 and
  36 .I argv
  37 (via the pointers
  38 .I argcp
  39 and
  40 .IR argvp ,
  41 which must point to the
  42 .I argc
  43 and
  44 .I argv
  45 being supplied to
  46 .IR getopt_long (3))
  47 accordingly.
  48 .I Optind
  49 must be the index, in the original argument vector,
  50 of the next argument.
  51 .PP
  52 If
  53 .I errsto
  54 is NULL,
  55 .I optionsfrom
  56 returns NULL for success and
  57 a pointer to a string-literal error message for failure;
  58 see DIAGNOSTICS.
  59 If
  60 .I errsto
  61 is non-NULL and an error occurs,
  62 .I optionsfrom
  63 prints a suitable complaint onto the
  64 .I errsto
  65 descriptor and invokes
  66 .I exit
  67 with an exit status of 2;
  68 this is a convenience for cases where more sophisticated
  69 responses are not required.
  70 .PP
  71 The text of existing arguments is not disturbed by
  72 .IR optionsfrom ,
  73 so pointers to them and into them remain valid.
  74 .PP
  75 The file of additional arguments is an ASCII text file.
  76 Lines consisting solely of white space,
  77 and lines beginning with
  78 .BR # ,
  79 are comments and are ignored.
  80 Otherwise, a line which does not begin with
  81 .BR \-
  82 is taken to be a single argument;
  83 if it both begins and ends with double-quote ("),
  84 those quotes are stripped off (note, no other processing is done within
  85 the line!).
  86 A line beginning with
  87 .B \-
  88 is considered to contain multiple arguments separated by white space.
  89 .PP
  90 Because
  91 .I optionsfrom
  92 reads its entire file before the
  93 .IR getopt_long (3)
  94 scan is resumed, an
  95 .I optionsfrom
  96 file can contain another
  97 .B \-\-optionsfrom
  98 option.
  99 Obviously, infinite loops are possible here.
 100 If
 101 .I errsto
 102 is non-NULL,
 103 .I optionsfrom
 104 considers it an error to be called more than 100 times.
 105 If
 106 .I errsto
 107 is NULL,
 108 loop detection is up to the caller
 109 (and the internal loop counter is zeroed out).
 110 .SH EXAMPLE
 111 A reasonable way to invoke
 112 .I optionsfrom
 113 would be like so:
 114 .PP
 115 .nf
 116 .ft B
 117 #include <getopt.h>
 118
 119 struct option opts[] = {
 120         /* ... */
 121         "optionsfrom",  1,      NULL,   '+',
 122         /* ... */
 123 };
 124
 125 int
 126 main(argc, argv)
 127 int argc;
 128 char *argv[];
 129 {
 130         int opt;
 131         extern char *optarg;
 132         extern int optind;
 133
 134         while ((opt = getopt_long(argc, argv, "", opts, NULL)) != EOF)
 135                 switch (opt) {
 136                 /* ... */
 137                 case '+':       /* optionsfrom */
 138                         optionsfrom(optarg, &argc, &argv, optind, stderr);
 139                         /* does not return on error */
 140                         break;
 141                 /* ... */
 142                 }
 143         /* ... */
 144 .ft
 145 .fi
 146 .SH SEE ALSO
 147 getopt_long(3)
 148 .SH DIAGNOSTICS
 149 Errors in
 150 .I optionsfrom
 151 are:
 152 unable to open file;
 153 attempt to allocate temporary storage for argument or
 154 argument vector failed;
 155 read error in file;
 156 line too long.
 157 .SH HISTORY
 158 Written for the FreeS/WAN project by Henry Spencer.
 159 .SH BUGS
 160 The double-quote convention is rather simplistic.
 161 .PP
 162 Line length is currently limited to 1023 bytes,
 163 and there is no continuation convention.
 164 .PP
 165 The restriction of error reports to literal strings
 166 (so that callers don't need to worry about freeing them or copying them)
 167 does limit the precision of error reporting.
 168 .PP
 169 The error-reporting convention lends itself
 170 to slightly obscure code,
 171 because many readers will not think of NULL as signifying success.
 172 .PP
 173 There is a certain element of unwarranted chumminess with
 174 the insides of
 175 .IR getopt_long (3)
 176 here.
 177 No non-public interfaces are actually used, but
 178 .IR optionsfrom
 179 does rely on
 180 .IR getopt_long (3)
 181 being well-behaved in certain ways that are not actually
 182 promised by the specs.