Standard I/O Streams
====================

   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, terminal input and output, but they are
often redirected with the shell, via the `<', `<<', `>', `>>', `>&' and
`|' operators.  Standard error is used only 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!\n" | "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 have often
neglected to do this.  Instead, they have sent the error messages to the
terminal, like this:

     NF != 4 {
        printf("line %d skipped: doesn't have 4 fields\n", FNR) > "/dev/tty"
     }

This has the same effect most of the time, 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, 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:

     NF != 4 {
       printf("line %d skipped: doesn't have 4 fields\n", FNR) > "/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 Files and Pipes: Close Input.).  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 blanks.  The fields
     represent the following information:

    `$1'
          The value of the `getuid' system call.

    `$2'
          The value of the `geteuid' system call.

    `$3'
          The value of the `getgid' system call.

    `$4'
          The value of the `getegid' system call.

     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 (see Invoking `awk': Command Line.).

     *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.