filestat

Prototype: filestat(filename, field)

Return type: string

Description: Returns the requested file field field for the file object filename.

If the file object does not exist, the function call fails and the variable does not expand.

Arguments:

• filename : the file or directory name to inspect, in the range: "?(/.*)
• field : the requested field, with the following allowed values:
  • size : size in bytes
  • gid : group ID
  • uid : owner ID
  • ino : inode number
  • nlink : number of hard links
  • ctime : creation time in Unix epoch format
  • atime : last access time in Unix epoch format
  • mtime : last modification time in Unix epoch format
  • mode : file mode as a decimal number
  • modeoct : file mode as an octal number, e.g. 10777
  • permstr : permission string, e.g. -rwx---rwx (not available on Windows)
  • permoct : permissions as an octal number, e.g. 644 (not available on Windows)
  • type : file type (not available on Windows): block device,character device, directory, FIFO/pipe, symlink, regular file, socket, or unknown
  • devno : device number (drive letter on Windows, e.g. C:)
  • dev_minor : minor device number (not available on Windows)
  • dev_major : major device number (not available on Windows)
  • basename : the file name minus the directory
  • dirname : the directory portion of the file name
  • linktarget : if the file is a symlink, its final target. The target is chased up to 32 levels of recursion. On Windows, this returns the file name itself.
  • linktarget_shallow : if the file is a symlink, its first target. On Windows, this returns the file name itself.
  • xattr : a string with newline-separated extended attributes and SELinux contexts in key=value<NEWLINE>key2=value2<NEWLINE>tag1<NEWLINE>tag2 format.

On Mac OS X, you can list and set extended attributes with the xattr utility.

On SELinux, the contexts are the same as what you see with ls -Z.

Example:

Prepare:

echo 1234567890 > FILE.txt
chmod 0755 FILE.txt
chown 0 FILE.txt
chgrp 0 FILE.txt

Run:

body common control
{
      bundlesequence => { "example" };
}

bundle agent example
{
  vars:
      "file" string => "$(this.promise_filename).txt";
  methods:
      "fileinfo" usebundle => fileinfo("$(file)");
}
bundle agent fileinfo(f)
{
  vars:
      # use the full list if you want to see all the attributes!
      # "fields" slist => splitstring("size,gid,uid,ino,nlink,ctime,atime,mtime,mode,modeoct,permstr,permoct,type,devno,dev_minor,dev_major,basename,dirname,linktarget,linktarget_shallow", ",", 999);

      # ino (inode number), ctime (creation time),
      # devno/dev_minor/dev_major (device numbers) were omitted but
      # they are all integers

      "fields" slist => splitstring("size,gid,uid,nlink,mode,modeoct,permstr,permoct,type,basename", ",", 999);

      "stat[$(f)][$(fields)]" string => filestat($(f), $(fields));

  reports:
      "$(this.bundle): file $(stat[$(f)][basename]) has $(fields) = $(stat[$(f)][$(fields)])";
}

Output:

R: fileinfo: file filestat.cf.txt has size = 11
R: fileinfo: file filestat.cf.txt has gid = 0
R: fileinfo: file filestat.cf.txt has uid = 0
R: fileinfo: file filestat.cf.txt has nlink = 1
R: fileinfo: file filestat.cf.txt has mode = 33261
R: fileinfo: file filestat.cf.txt has modeoct = 100755
R: fileinfo: file filestat.cf.txt has permstr = -rwxr-xr-x
R: fileinfo: file filestat.cf.txt has permoct = 755
R: fileinfo: file filestat.cf.txt has type = regular file
R: fileinfo: file filestat.cf.txt has basename = filestat.cf.txt

Notes:

• linktarget will prepend the directory name to relative symlink targets, in order to be able to resolve them. Use linktarget_shallow to get the exact link as-is in case it is a relative link.
• The list of fields may be extended as needed by CFEngine.

History: Was introduced in version 3.5.0,Enterprise 3.1 (2013). linktarget and linktarget_shallow were added in version 3.6.

See also: lastnode(), dirname(), splitstring().