filefuncs man page on Archlinux

Man page or keyword search:  
man Server   11224 pages
apropos Keyword Search (all sections)
Output format
Archlinux logo
[printable version]

FILEFUNCS(3am)		   GNU Awk Extension Modules		FILEFUNCS(3am)

       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 success‐
       ful, 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 ele‐
	      ment is only present for device files.

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

	      Corresponds to the st_minor field in the struct stat.  This ele‐
	      ment 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  sym‐
	      bolic 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 FTS_LOGI‐

		     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 ele‐
	      ment 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()	 func‐
			    tion  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 ele‐
		     ment  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 nat‐
       ural  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  man‐
       ual page into another language, under the above conditions for modified
       versions, except that this permission notice may be stated in a	trans‐
       lation approved by the Foundation.

Free Software Foundation	  Jan 15 2013			FILEFUNCS(3am)

List of man pages available for Archlinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net