gawk: Extension Sample File Functions
1
1 16.7.1 File-Related Functions
1 -----------------------------
1
1 The 'filefuncs' extension provides three different functions, as
1 follows. The usage is:
1
1 '@load "filefuncs"'
1 This is how you load the extension.
1
1 'result = chdir("/some/directory")'
1 The 'chdir()' function is a direct hook to the 'chdir()' system
1 call to change the current directory. It returns zero upon success
1 or a value less than zero upon error. In the latter case, it
1 updates 'ERRNO'.
1
1 'result = stat("/some/path", statdata' [', follow']')'
1 The 'stat()' function provides a hook into the 'stat()' system
1 call. It returns zero upon success or a value less than zero upon
1 error. In the latter case, it updates 'ERRNO'.
1
1 By default, it uses the 'lstat()' system call. However, if passed
1 a third argument, it uses 'stat()' instead.
1
1 In all cases, it clears the 'statdata' array. When the call is
1 successful, 'stat()' fills the 'statdata' array with information
1 retrieved from the filesystem, as follows:
1
1 Subscript Field in 'struct stat' File type
1 ----------------------------------------------------------------
1 '"name"' The file name All
1 '"dev"' 'st_dev' All
1 '"ino"' 'st_ino' All
1 '"mode"' 'st_mode' All
1 '"nlink"' 'st_nlink' All
1 '"uid"' 'st_uid' All
1 '"gid"' 'st_gid' All
1 '"size"' 'st_size' All
1 '"atime"' 'st_atime' All
1 '"mtime"' 'st_mtime' All
1 '"ctime"' 'st_ctime' All
1 '"rdev"' 'st_rdev' Device files
1 '"major"' 'st_major' Device files
1 '"minor"' 'st_minor' Device files
1 '"blksize"' 'st_blksize' All
1 '"pmode"' A human-readable version of the All
1 mode value, like that printed by
1 'ls' (for example, '"-rwxr-xr-x"')
1 '"linkval"' The value of the symbolic link Symbolic
1 links
1 '"type"' The type of the file as a All
1 string--one of '"file"',
1 '"blockdev"', '"chardev"',
1 '"directory"', '"socket"',
1 '"fifo"', '"symlink"', '"door"',
1 or '"unknown"' (not all systems
1 support all file types)
1
1 'flags = or(FTS_PHYSICAL, ...)'
1 'result = fts(pathlist, flags, filedata)'
1 Walk the file trees provided in 'pathlist' and fill in the
1 'filedata' array, as described next. 'flags' is the bitwise OR of
1 several predefined values, also described in a moment. Return zero
1 if there were no errors, otherwise return -1.
1
1 The 'fts()' function provides a hook to the C library 'fts()'
1 routines for traversing file hierarchies. Instead of returning data
1 about one file at a time in a stream, it fills in a multidimensional
1 array with data about each file and directory encountered in the
1 requested hierarchies.
1
1 The arguments are as follows:
1
1 'pathlist'
1 An array of file names. The element values are used; the index
1 values are ignored.
1
1 'flags'
1 This should be the bitwise OR of one or more of the following
1 predefined constant flag values. At least one of 'FTS_LOGICAL' or
1 'FTS_PHYSICAL' must be provided; otherwise 'fts()' returns an error
1 value and sets 'ERRNO'. The flags are:
1
1 'FTS_LOGICAL'
1 Do a "logical" file traversal, where the information returned
1 for a symbolic link refers to the linked-to file, and not to
1 the symbolic link itself. This flag is mutually exclusive
1 with 'FTS_PHYSICAL'.
1
1 'FTS_PHYSICAL'
1 Do a "physical" file traversal, where the information returned
1 for a symbolic link refers to the symbolic link itself. This
1 flag is mutually exclusive with 'FTS_LOGICAL'.
1
1 'FTS_NOCHDIR'
1 As a performance optimization, the C library 'fts()' routines
1 change directory as they traverse a file hierarchy. This flag
1 disables that optimization.
1
1 'FTS_COMFOLLOW'
1 Immediately follow a symbolic link named in 'pathlist',
1 whether or not 'FTS_LOGICAL' is set.
1
1 'FTS_SEEDOT'
1 By default, the C library 'fts()' routines do not return
1 entries for '.' (dot) and '..' (dot-dot). This option causes
1 entries for dot-dot to also be included. (The extension
1 always includes an entry for dot; more on this in a moment.)
1
1 'FTS_XDEV'
1 During a traversal, do not cross onto a different mounted
1 filesystem.
1
1 'filedata'
1 The 'filedata' array holds the results. 'fts()' first clears it.
1 Then it creates an element in 'filedata' for every element in
1 'pathlist'. The index is the name of the directory or file given
1 in 'pathlist'. The element for this index is itself an array.
1 There are two cases:
1
1 _The path is a file_
1 In this case, the array contains two or three elements:
1
1 '"path"'
1 The full path to this file, starting from the "root" that
1 was given in the 'pathlist' array.
1
1 '"stat"'
1 This element is itself an array, containing the same
1 information as provided by the 'stat()' function
1 described earlier for its 'statdata' argument. The
1 element may not be present if the 'stat()' system call
1 for the file failed.
1
1 '"error"'
1 If some kind of error was encountered, the array will
1 also contain an element named '"error"', which is a
1 string describing the error.
1
1 _The path is a directory_
1 In this case, the array contains one element for each entry in
1 the directory. If an entry is a file, that element is the
1 same as for files, just described. If the entry is a
1 directory, that element is (recursively) an array describing
1 the subdirectory. If 'FTS_SEEDOT' was provided in the flags,
1 then there will also be an element named '".."'. This element
1 will be an array containing the data as provided by 'stat()'.
1
1 In addition, there will be an element whose index is '"."'.
1 This element is an array containing the same two or three
1 elements as for a file: '"path"', '"stat"', and '"error"'.
1
1 The 'fts()' function returns zero if there were no errors.
1 Otherwise, it returns -1.
1
1 NOTE: The 'fts()' extension does not exactly mimic the interface of
1 the C library 'fts()' routines, choosing instead to provide an
1 interface that is based on associative arrays, which is more
1 comfortable to use from an 'awk' program. This includes the lack
1 of a comparison function, because 'gawk' already provides powerful
1 array sorting facilities. Although an 'fts_read()'-like interface
1 could have been provided, this felt less natural than simply
1 creating a multidimensional array to represent the file hierarchy
1 and its information.
1
1 See 'test/fts.awk' in the 'gawk' distribution for an example use of
1 the 'fts()' extension function.
1