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