(gawk.info)Special Files

Special File Names in `gawk'
============================

   Running programs conventionally have three input and output streams
already available to them for reading and writing.  These are known as
the "standard input", "standard output", and "standard error output".
These streams are, by default, connected to your terminal, but they are
often redirected with the shell, via the `<', `<<', `>', `>>', `>&' and
`|' operators.  Standard error is typically used for writing error
messages; the reason we have two separate streams, standard output and
standard error, is so that they can be redirected separately.

   In other implementations of `awk', the only way to write an error
message to standard error in an `awk' program is as follows:

     print "Serious error detected!" | "cat 1>&2"

This works by opening a pipeline to a shell command which can access the
standard error stream which it inherits from the `awk' process.  This
is far from elegant, and is also inefficient, since it requires a
separate process.  So people writing `awk' programs often neglect to do
this.  Instead, they send the error messages to the terminal, like this:

     print "Serious error detected!" > "/dev/tty"

This usually has the same effect, but not always: although the standard
error stream is usually the terminal, it can be redirected, and when
that happens, writing to the terminal is not correct.  In fact, if
`awk' is run from a background job, it may not have a terminal at all.
Then opening `/dev/tty' will fail.

   `gawk' provides special file names for accessing the three standard
streams.  When you redirect input or output in `gawk', if the file name
matches one of these special names, then `gawk' directly uses the
stream it stands for.

`/dev/stdin'
     The standard input (file descriptor 0).

`/dev/stdout'
     The standard output (file descriptor 1).

`/dev/stderr'
     The standard error output (file descriptor 2).

`/dev/fd/N'
     The file associated with file descriptor N.  Such a file must have
     been opened by the program initiating the `awk' execution
     (typically the shell).  Unless you take special pains in the shell
     from which you invoke `gawk', only descriptors 0, 1 and 2 are
     available.

   The file names `/dev/stdin', `/dev/stdout', and `/dev/stderr' are
aliases for `/dev/fd/0', `/dev/fd/1', and `/dev/fd/2', respectively,
but they are more self-explanatory.

   The proper way to write an error message in a `gawk' program is to
use `/dev/stderr', like this:

     print "Serious error detected!" > "/dev/stderr"

   `gawk' also provides special file names that give access to
information about the running `gawk' process.  Each of these "files"
provides a single record of information.  To read them more than once,
you must first close them with the `close' function (Note: Closing
Input and Output Files and Pipes.).  The
filenames are:

`/dev/pid'
     Reading this file returns the process ID of the current process,
     in decimal, terminated with a newline.

`/dev/ppid'
     Reading this file returns the parent process ID of the current
     process, in decimal, terminated with a newline.

`/dev/pgrpid'
     Reading this file returns the process group ID of the current
     process, in decimal, terminated with a newline.

`/dev/user'
     Reading this file returns a single record terminated with a
     newline.  The fields are separated with spaces.  The fields
     represent the following information:

    `$1'
          The return value of the `getuid' system call (the real user
          ID number).

    `$2'
          The return value of the `geteuid' system call (the effective
          user ID number).

    `$3'
          The return value of the `getgid' system call (the real group
          ID number).

    `$4'
          The return value of the `getegid' system call (the effective
          group ID number).

     If there are any additional fields, they are the group IDs
     returned by `getgroups' system call.  (Multiple groups may not be
     supported on all systems.)

   These special file names may be used on the command line as data
files, as well as for I/O redirections within an `awk' program.  They
may not be used as source files with the `-f' option.

   Recognition of these special file names is disabled if `gawk' is in
compatibility mode (Note: Command Line Options.).

   *Caution*:  Unless your system actually has a `/dev/fd' directory
(or any of the other above listed special files), the interpretation of
these file names is done by `gawk' itself.  For example, using
`/dev/fd/4' for output will actually write on file descriptor 4, and
not on a new file descriptor that was `dup''ed from file descriptor 4.
Most of the time this does not matter; however, it is important to
*not* close any of the files related to file descriptors 0, 1, and 2.
If you do close one of these files, unpredictable behavior will result.

   The special files that provide process-related information may
disappear in a future version of `gawk'.  Note: Probable Future
Extensions.