File: gawk.info,  Node: Internal File Description,  Next: Internal File Ops,  Up: Extension Example

17.6.1 Using 'chdir()' and 'stat()'
-----------------------------------

This minor node shows how to use the new functions at the 'awk' level
once they've been integrated into the running 'gawk' interpreter.  Using
'chdir()' is very straightforward.  It takes one argument, the new
directory to change to:

     @load "filefuncs"
     ...
     newdir = "/home/arnold/funstuff"
     ret = chdir(newdir)
     if (ret < 0) {
         printf("could not change to %s: %s\n", newdir, ERRNO) > "/dev/stderr"
         exit 1
     }
     ...

   The return value is negative if the 'chdir()' failed, and 'ERRNO'
(*note Built-in Variables::) is set to a string indicating the error.

   Using 'stat()' is a bit more complicated.  The C 'stat()' function
fills in a structure that has a fair amount of information.  The right
way to model this in 'awk' is to fill in an associative array with the
appropriate information:

     file = "/home/arnold/.profile"
     ret = stat(file, fdata)
     if (ret < 0) {
         printf("could not stat %s: %s\n",
                  file, ERRNO) > "/dev/stderr"
         exit 1
     }
     printf("size of %s is %d bytes\n", file, fdata["size"])

   The 'stat()' function always clears the data array, even if the
'stat()' fails.  It fills in the following elements:

'"name"'
     The name of the file that was 'stat()'ed.

'"dev"'
'"ino"'
     The file's device and inode numbers, respectively.

'"mode"'
     The file's mode, as a numeric value.  This includes both the file's
     type and its permissions.

'"nlink"'
     The number of hard links (directory entries) the file has.

'"uid"'
'"gid"'
     The numeric user and group ID numbers of the file's owner.

'"size"'
     The size in bytes of the file.

'"blocks"'
     The number of disk blocks the file actually occupies.  This may not
     be a function of the file's size if the file has holes.

'"atime"'
'"mtime"'
'"ctime"'
     The file's last access, modification, and inode update times,
     respectively.  These are numeric timestamps, suitable for
     formatting with 'strftime()' (*note Time Functions::).

'"pmode"'
     The file's "printable mode."  This is a string representation of
     the file's type and permissions, such as is produced by 'ls
     -l'--for example, '"drwxr-xr-x"'.

'"type"'
     A printable string representation of the file's type.  The value is
     one of the following:

     '"blockdev"'
     '"chardev"'
          The file is a block or character device ("special file").

     '"directory"'
          The file is a directory.

     '"fifo"'
          The file is a named pipe (also known as a FIFO).

     '"file"'
          The file is just a regular file.

     '"socket"'
          The file is an 'AF_UNIX' ("Unix domain") socket in the
          filesystem.

     '"symlink"'
          The file is a symbolic link.

'"devbsize"'
     The size of a block for the element indexed by '"blocks"'.  This
     information is derived from either the 'DEV_BSIZE' constant defined
     in '' on most systems, or the 'S_BLKSIZE' constant in
     '' on BSD systems.  For some other systems, "a priori"
     knowledge is used to provide a value.  Where no value can be
     determined, it defaults to 512.

   Several additional elements may be present, depending upon the
operating system and the type of the file.  You can test for them in
your 'awk' program by using the 'in' operator (*note Reference to
Elements::):

'"blksize"'
     The preferred block size for I/O to the file.  This field is not
     present on all POSIX-like systems in the C 'stat' structure.

'"linkval"'
     If the file is a symbolic link, this element is the name of the
     file the link points to (i.e., the value of the link).

'"rdev"'
'"major"'
'"minor"'
     If the file is a block or character device file, then these values
     represent the numeric device number and the major and minor
     components of that number, respectively.