(no commit message)
[strongswan.git] / src / libfreeswan / optionsfrom.3
1 .TH IPSEC_OPTIONSFROM 3 "16 Oct 1998"
2 .\" RCSID $Id: optionsfrom.3,v 1.1 2004/03/15 20:35:26 as 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.