Imported Upstream version 93u+upstream

1 files changed, 126 insertions, 0 deletions

diff --git a/src/lib/libast/man/vecargs.3 b/src/lib/libast/man/vecargs.3
new file mode 100644
index 0000000..29e492b
--- /dev/null
+++ b/src/lib/libast/man/vecargs.3
@@ -0,0 +1,126 @@
+.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.