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 : time of last change 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:

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

Run:

code
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:

code
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:

  • function introduced in version 3.5.0.
  • linktarget and linktarget_shallow field options added in 3.6.0.

See also: dirname(), fileexists(), isdir(), islink(), isplain(), lastnode(), returnszero(), splitstring().