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