filefuncs - provide some file related functionality to gawk


   @load "filefuncs"

   result = chdir("/some/directory")

   result = stat("/some/path", statdata [, follow])

   flags = or(FTS_PHYSICAL, ...)
   result = fts(pathlist, flags, filedata)


   The  filefuncs  extension adds several functions that provide access to
   file-related facilities.

   The chdir() function is a direct hook to the chdir(2)  system  call  to
   change  the  current  directory.   It returns zero upon success or less
   than zero upon error.  In the latter case it updates ERRNO.

   The stat() function provides a hook into the stat(2) system  call.   It
   returns  zero upon success or less than zero upon error.  In the latter
   case it updates ERRNO.  By default,  it  uses  lstat(2).   However,  if
   passed a third argument, it uses stat(2), instead.

   In  all  cases,  it  clears  the  statdata  array.   When  the  call is
   successful, stat() fills the statdata array with information  retrieved
   from the filesystem, as follows:

          The name of the file.

          Corresponds to the st_dev field in the struct stat.

          Corresponds to the st_ino field in the struct stat.

          Corresponds to the st_mode field in the struct stat.

          Corresponds to the st_nlink field in the struct stat.

          Corresponds to the st_uid field in the struct stat.

          Corresponds to the st_gid field in the struct stat.

          Corresponds to the st_size field in the struct stat.

          Corresponds to the st_atime field in the struct stat.

          Corresponds to the st_mtime field in the struct stat.

          Corresponds to the st_ctime field in the struct stat.

          Corresponds  to  the  st_rdev  field  in  the struct stat.  This
          element is only present for device files.

          Corresponds to the st_major field  in  the  struct  stat.   This
          element is only present for device files.

          Corresponds  to  the  st_minor  field  in the struct stat.  This
          element is only present for device files.

          Corresponds to the st_blksize field in the struct stat, if  this
          field  is  present on your system.  (It is present on all modern
          systems that we know of.)

          A human-readable version of the mode value, such as  printed  by
          ls(1).  For example, "-rwxr-xr-x".

          If  the  named  file is a symbolic link, this element will exist
          and its value is the value  of  the  symbolic  link  (where  the
          symbolic link points to).

          The  type  of  the  file as a string. One of "file", "blockdev",
          "chardev", "directory", "socket", "fifo", "symlink", "door",  or
          "unknown".  Not all systems support all file types.

   The  fts()  function  provides a hook to the fts(3) set of routines for
   traversing file heirarchies.  Instead of returning data about one  file
   at  a time in a stream, it fills in a multi-dimensional array with data
   about each file and directory encountered in the requested heirarchies.

   The arguments are as follows:

          An array of filenames.  The element values are used;  the  index
          values are ignored.

   flags  This  should  be  the bitwise OR of one or more of the following
          predefined  flag  values.   At  least  one  of  FTS_LOGICAL   or
          FTS_PHYSICAL  must be provided; otherwise fts() returns an error
          value and sets ERRNO.

                 Do a ``logical'' file traversal,  where  the  information
                 returned  for  a  symbolic  link  refers to the linked-to
                 file, and not to the symbolic link itself.  This flag  is
                 mutually exclusive with FTS_PHYSICAL.

                 Do  a  ``physical'' file traversal, where the information
                 returned for a symbolic link refers to the symbolic  link
                 itself.    This   flag   is   mutually   exclusive   with

                 As a performance optimization, the fts(3) routines change
                 directory  as  they traverse a file heirarchy.  This flag
                 disables that optimization.

                 Immediatly follow a  symbolic  link  named  in  pathlist,
                 whether or not FTS_LOGICAL is set.

                 By default, the fts(3) routines do not return entries for
                 ``.'' and ``..''.  This option causes entries for  ``..''
                 to  also be included.  (The AWK extension always includes
                 an entry for ``.'', see below.)

                 During a traversal, do not cross onto a different mounted

          The  filedata  array  is  first cleared.  Then, fts() creates an
          element in filedata for every element in pathlist.  The index is
          the  name  of  the  directory  or  file  given in pathlist.  The
          element for this index is itself an array.  There are two cases.

          The path is a file.
                 In this case, the array contains two or three elements:

                 "path" The full path to  this  file,  starting  from  the
                        ``root'' that was given in the pathlist array.

                 "stat" This  element  is  itself an array, containing the
                        same  information  as  provided  by   the   stat()
                        function   described   earlier  for  its  statdata
                        argument.  The  element  may  not  be  present  if
                        stat(2) for the file failed.

                        If  some  kind of error was encountered, the array
                        will also contain an element named "error",  which
                        is a string describing the error.

          The path is a directory.
                 In  this  case,  the  array contains one element for each
                 entry in the directory.  If an  entry  is  a  file,  that
                 element is as for files, just described.  If the entry is
                 a directory, that  element  is  (recursively),  an  array
                 describing  the subdirectory.  If FTS_SEEDOT was provided
                 in the flags, then there will also be  an  element  named
                 "..".   This element will be an array containing the data
                 as provided by stat().

                 In addition, there will be an element whose index is ".".
                 This element is an array containing the same two or three
                 elements as for a file: "path", "stat", and "error".

   The fts() function returns 0 if there  were  no  errors.  Otherwise  it
   returns -1.


   The  AWK  fts()  extension  does not exactly mimic the interface of the
   fts(3) routines, choosing instead to provide an interface that is based
   on  associative arrays, which should be more comfortable to use from an
   AWK program.  This includes the lack of a  comparison  function,  since
   gawk  already  provides  powerful  array  sorting facilities.  While an
   fts_read()-like interface could have  been  provided,  this  felt  less
   natural than simply creating a multi-dimensional array to represent the
   file heirarchy and its information.

   Nothing prevents AWK code from changing the predefined  FTS_xx  values,
   but  doing  so is may cause strange results when the changed values are
   passed to fts().


   There are many more file-related functions  for  which  AWK  interfaces
   would be desirable.


   See test/fts.awk in the gawk distribution for an example.


   GAWK: Effective AWK Programming, fnmatch(3am), fork(3am), inplace(3am),
   ordchr(3am), readdir(3am), readfile(3am), revoutput(3am), rwarray(3am),

   chdir(2), fts(3), stat(2).


   Arnold Robbins,


   Copyright  2012, 2013, Free Software Foundation, Inc.

   Permission  is  granted  to make and distribute verbatim copies of this
   manual page provided the copyright notice and  this  permission  notice
   are preserved on all copies.

   Permission  is granted to copy and distribute modified versions of this
   manual page under the conditions for verbatim  copying,  provided  that
   the  entire  resulting derived work is distributed under the terms of a
   permission notice identical to this one.

   Permission is granted to  copy  and  distribute  translations  of  this
   manual  page  into  another  language,  under  the above conditions for
   modified versions, except that this permission notice may be stated  in
   a translation approved by the Foundation.


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.

Free Software

Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.

Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.

Free Books

The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.

Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.

Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.