GNU Info

(gawk.info)AWKPATH Variable

---

Next: Obsolete Prev: Other Arguments Up: Invoking Gawk

---

Enter node , (file) or (file)node

The `AWKPATH' Environment Variable
==================================

   The previous minor node described how `awk' program files can be
named on the command-line with the `-f' option.  In most `awk'
implementations, you must supply a precise path name for each program
file, unless the file is in the current directory.  But in `gawk', if
the file name supplied to the `-f' option does not contain a `/', then
`gawk' searches a list of directories (called the "search path"), one
by one, looking for a file with the specified name.

   The search path is a string consisting of directory names separated
by colons.  `gawk' gets its search path from the `AWKPATH' environment
variable.  If that variable does not exist, `gawk' uses a default path,
which is `.:/usr/local/share/awk'.(1) (Programs written for use by
system administrators should use an `AWKPATH' variable that does not
include the current directory, `.'.)

   The search path feature is particularly useful for building libraries
of useful `awk' functions.  The library files can be placed in a
standard directory in the default path and then specified on the
command-line with a short file name.  Otherwise, the full file name
would have to be typed for each file.

   By using both the `--source' and `-f' options, your command-line
`awk' programs can use facilities in `awk' library files.  Note: A
Library of `awk' Functions.  Path searching is not
done if `gawk' is in compatibility mode.  This is true for both
`--traditional' and `--posix'.  Note: Command-Line Options.

   *Note:* If you want files in the current directory to be found, you
must include the current directory in the path, either by including `.'
explicitly in the path or by writing a null entry in the path.  (A null
entry is indicated by starting or ending the path with a colon or by
placing two colons next to each other (`::').)  If the current
directory is not included in the path, then files cannot be found in
the current directory.  This path search mechanism is identical to the
shell's.

   Starting with version 3.0, if `AWKPATH' is not defined in the
environment, `gawk' places its default search path into
`ENVIRON["AWKPATH"]'. This makes it easy to determine the actual search
path that `gawk' will use from within an `awk' program.

   While you can change `ENVIRON["AWKPATH"]' within your `awk' program,
this has no effect on the running program's behavior.  This makes
sense: the `AWKPATH' environment variable is used to find the program
source files.  Once your program is running, all the files have been
found, and `gawk' no longer needs to use `AWKPATH'.

   ---------- Footnotes ----------

   (1) Your version of `gawk' may use a different directory; it will
depend upon how `gawk' was built and installed. The actual directory is
the value of `$(datadir)' generated when `gawk' was configured.  You
probably don't need to worry about this though.