.fp 5 CW
.de Af
.ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
.if !\\$4 .Af \\$2 \\$1 "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
..
.de aF
.ie \\$3 .ft \\$1
.el \{\
.ds ;G \&
.nr ;G \\n(.f
.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
\\*(;G
.ft \\n(;G \}
..
.de L
.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de LR
.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de RL
.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de EX \" start example
.ta 1i 2i 3i 4i 5i 6i
.PP
.RS
.PD 0
.ft 5
.nf
..
.de EE \" end example
.fi
.ft
.PD
.RE
.PP
..
.TH VECARGS 3
.SH NAME
vecargs \- command argument vector insertion routines
.SH SYNOPSIS
.L "#include <vecargs.h>"
.sp
.L "char** vecload(char* string);"
.L "char** vecfile(const char* path);"
.L "char** vecstring(const char* string);"
.L "void vecfree(char**, int);"
.L "int vecargs(char** vec, int* argcp, char*** argvp);"
.SH DESCRIPTION
.L vecload
loads a string vector from lines in
.LR string .
.L string
may be modified upon return.
Each line in
.L string
is treated as a new vector element.
Lines with
.L #
as the first character are comments.
.I \enewline
joins consecutive lines.
A string vector pointer is returned, 0 on error.
.PP
.L vecfile
constructs a string vector by calling
.L vecload
on the contents of the file named by
.LR path .
The string vector pointer is returned, 0 on error.
.PP
.L vecstring
constructs a string vector by calling
.L vecload
on a copy of
.LR string .
The string vector pointer is returned, 0 on error.
.PP
.L vecfree
frees a string vector allocated by
.LR vecfile ,
.L vecload
or
.LR vecstring .
.PP
.L vecargs
inserts the string vector
.L vec
(as returned by
.LR vecfile ,
.L vecload
or
.LR vecstring )
between
.L "(*argvp)[0]"
and
.LR "(*argvp)[1]" ,
sliding
.L "(*argvp)[1] ..."
over.
NULL and empty string args in
.L vec
are not copied.
.L "vecfree(vec)"
is called before the return.
.L \-1
is returned if the insertion failed.
.SH EXAMPLES
.L vecargs
is commonly used to modify command
.L argv
from fixed files.
For example,
.IR make (1)
checks for the files
.L ./Makeargs
and
.L ./makeargs
to modify its arguments on startup.
Its a handy way to override default options on a directory by directory basis
without modify the standard control files
(\f5Makefile\fP in this case.)
.SH CAVEATS
This paradigm is not recommended for all commands; only a few exceptions
make sense.