usr/src/lib/libast/common/man/vecargs.3

   1 .fp 5 CW
   2 .de Af
   3 .ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
   4 .if !\a\\$4\a\a .Af \\$2 \\$1 "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
   5 ..
   6 .de aF
   7 .ie \a\\$3\a\a .ft \\$1
   8 .el \{\
   9 .ds ;G \&
  10 .nr ;G \\n(.f
  11 .Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
  12 \\*(;G
  13 .ft \\n(;G \}
  14 ..
  15 .de L
  16 .aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
  17 ..
  18 .de LR
  19 .aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
  20 ..
  21 .de RL
  22 .aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
  23 ..
  24 .de EX          \" start example
  25 .ta 1i 2i 3i 4i 5i 6i
  26 .PP
  27 .RS
  28 .PD 0
  29 .ft 5
  30 .nf
  31 ..
  32 .de EE          \" end example
  33 .fi
  34 .ft
  35 .PD
  36 .RE
  37 .PP
  38 ..
  39 .TH VECARGS 3
  40 .SH NAME
  41 vecargs \- command argument vector insertion routines
  42 .SH SYNOPSIS
  43 .L "#include <vecargs.h>"
  44 .sp
  45 .L "char** vecload(char* string);"
  46 .L "char** vecfile(const char* path);"
  47 .L "char** vecstring(const char* string);"
  48 .L "void vecfree(char**, int);"
  49 .L "int vecargs(char** vec, int* argcp, char*** argvp);"
  50 .SH DESCRIPTION
  51 .L vecload
  52 loads a string vector from lines in
  53 .LR string .
  54 .L string
  55 may be modified upon return.
  56 Each line in
  57 .L string
  58 is treated as a new vector element.
  59 Lines with
  60 .L #
  61 as the first character are comments.
  62 .I \enewline
  63 joins consecutive lines.
  64 A string vector pointer is returned, 0 on error.
  65 .PP
  66 .L vecfile
  67 constructs a string vector by calling
  68 .L vecload
  69 on the contents of the file named by
  70 .LR path .
  71 The string vector pointer is returned, 0 on error.
  72 .PP
  73 .L vecstring
  74 constructs a string vector by calling
  75 .L vecload
  76 on a copy of
  77 .LR string .
  78 The string vector pointer is returned, 0 on error.
  79 .PP
  80 .L vecfree
  81 frees a string vector allocated by
  82 .LR vecfile ,
  83 .L vecload
  84 or
  85 .LR vecstring .
  86 .PP
  87 .L vecargs
  88 inserts the string vector
  89 .L vec
  90 (as returned by
  91 .LR vecfile ,
  92 .L vecload
  93 or
  94 .LR vecstring )
  95 between
  96 .L "(*argvp)[0]"
  97 and
  98 .LR "(*argvp)[1]" ,
  99 sliding
 100 .L "(*argvp)[1] ..."
 101 over.
 102 NULL and empty string args in
 103 .L vec
 104 are not copied.
 105 .L "vecfree(vec)"
 106 is called before the return.
 107 .L \-1
 108 is returned if the insertion failed.
 109 .SH EXAMPLES
 110 .L vecargs
 111 is commonly used to modify command
 112 .L argv
 113 from fixed files.
 114 For example,
 115 .IR make (1)
 116 checks for the files
 117 .L ./Makeargs
 118 and
 119 .L ./makeargs
 120 to modify its arguments on startup.
 121 Its a handy way to override default options on a directory by directory basis
 122 without modify the standard control files
 123 (\f5Makefile\fP in this case.)
 124 .SH CAVEATS
 125 This paradigm is not recommended for all commands; only a few exceptions
 126 make sense.