.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.