gawk: AWKPATH Variable
1
1 2.5.1 The 'AWKPATH' Environment Variable
1 ----------------------------------------
1
1 The previous minor node described how 'awk' program files can be named
1 on the command line with the '-f' option. In most 'awk'
1 implementations, you must supply a precise pathname for each program
1 file, unless the file is in the current directory. But with 'gawk', if
1 the file name supplied to the '-f' or '-i' options does not contain a
1 directory separator '/', then 'gawk' searches a list of directories
1 (called the "search path") one by one, looking for a file with the
1 specified name.
1
1 The search path is a string consisting of directory names separated
1 by colons.(1) 'gawk' gets its search path from the 'AWKPATH'
1 environment variable. If that variable does not exist, or if it has an
1 empty value, 'gawk' uses a default path (described shortly).
1
1 The search path feature is particularly helpful for building
1 libraries of useful 'awk' functions. The library files can be placed in
1 a standard directory in the default path and then specified on the
1 command line with a short file name. Otherwise, you would have to type
1 the full file name for each file.
1
1 By using the '-i' or '-f' options, your command-line 'awk' programs
1 can use facilities in 'awk' library files (⇒Library Functions).
1 Path searching is not done if 'gawk' is in compatibility mode. This is
1 true for both '--traditional' and '--posix'. ⇒Options.
1
1 If the source code file is not found after the initial search, the
1 path is searched again after adding the suffix '.awk' to the file name.
1
1 'gawk''s path search mechanism is similar to the shell's. (See 'The
1 Bourne-Again SHell manual' (https://www.gnu.org/software/bash/manual/).)
1 It treats a null entry in the path as indicating the current directory.
1 (A null entry is indicated by starting or ending the path with a colon
1 or by placing two colons next to each other ['::'].)
1
1 NOTE: To include the current directory in the path, either place
1 '.' as an entry in the path or write a null entry in the path.
1
1 Different past versions of 'gawk' would also look explicitly in the
1 current directory, either before or after the path search. As of
1 version 4.1.2, this no longer happens; if you wish to look in the
1 current directory, you must include '.' either as a separate entry
1 or as a null entry in the search path.
1
1 The default value for 'AWKPATH' is '.:/usr/local/share/awk'.(2)
1 Since '.' is included at the beginning, 'gawk' searches first in the
1 current directory and then in '/usr/local/share/awk'. In practice, this
1 means that you will rarely need to change the value of 'AWKPATH'.
1
1 ⇒Shell Startup Files, for information on functions that help
1 to manipulate the 'AWKPATH' variable.
1
1 'gawk' places the value of the search path that it used into
1 'ENVIRON["AWKPATH"]'. This provides access to the actual search path
1 value from within an 'awk' program.
1
1 Although you can change 'ENVIRON["AWKPATH"]' within your 'awk'
1 program, this has no effect on the running program's behavior. This
1 makes sense: the 'AWKPATH' environment variable is used to find the
1 program source files. Once your program is running, all the files have
1 been found, and 'gawk' no longer needs to use 'AWKPATH'.
1
1 ---------- Footnotes ----------
1
1 (1) Semicolons on MS-Windows.
1
1 (2) Your version of 'gawk' may use a different directory; it will
1 depend upon how 'gawk' was built and installed. The actual directory is
1 the value of '$(datadir)' generated when 'gawk' was configured. You
1 probably don't need to worry about this, though.
1