&stat(4)

NAME

&stat - Retrieve a file statistic

SYNOPSIS

&stat <stat> <filename>

DESCRIPTION

&stat returns the specified <stat> on the given <filename>. Valid <stat> values are:

a


Returns the absolute file name, corrects relative paths and symbolic links, i.e. on UNIX if the filename is a symbolic link it returns the file name the link points to (recursive), otherwise returns the file name.

d


Returns the file's modification time stamp as an integer, larger values indicate a later time.

i


Returns information on the file in a MicroEmacs list formatted string. The fields within the list are defined as follows:

1


File location, which will be one of the following:

    F   File is an ftp URL file (see note). 
    H   File is a http URL link (see note). 
    L   File is a local file (may be prefixed with 'file:'). 
    T   File is a tfs file (tfs://...). 

2


File type, which will be one of the following:

    D   File is a directory. 
    H   File is a http URL link (no further information is known). 
    L   File is a symbolic link (UNIX). 
    N   File is an untouchable system file. 
    R   File is a regular file. 
    X   File does not exist. 

Note the information returned here is different to the 't' flag below as the type of an ftp file is evaluated, i.e. D, R or X will be returned.

3


Symbolic file type, which will be the empty string unless the file type above is 'L' in which case it will be one of the following:

    D   File is a directory. 
    N   File is an untouchable system file. 
    R   File is a regular file. 
    X   File does not exist. 

4


File permissions or attributes which are returned as an integer value specific to the Operating System.

5 and 6


File size given as an upper and lower 32 bit integers for large file support, these values will be the empty string if the file size could not be determined.

7


File modification time given as "YYYYMMDDhhmmss", this field has not yet been implemented.

m


Returns the file's modification time stamp as a string, the format of the string is the same as $time(5).

r


Returns a non-zero value if the user has permission to read the given file.

s


Returns the size of the file in bytes.

t


Returns the type of the file, where values returned are

    X   File does not exist. 
    R   File is a regular file. 
    D   File is a directory. 
    H   File is a http URL link (see note). 
    F   File is an ftp URL file (see note). 
    N   File is an untouchable system file. 

w


Returns a non-zero value if the user has permission to write to the given file. Note that 0 is simply returned for ftp URLs whereas the user may have write permission depending on the server and login credentials supplied.

x


Returns a non-zero value if the user has permission to execute the given file.

NOTES

The URL type is determined from the start of the file name, e.g. http://..., and its existence is never verified if a http, nor for an ftp URL except for an i stat.

The following URL types are supported depending on the build of MicroEmacs:

    file:     Local file. 
    ftp://    Standard ftp URL (default port 21). 
    ftpe://   Explicit secure ftp (default port 21). 
    ftps://   Implicit secure ftp (default port 990). 
    http://   Standard http URL (default port 80). 
    https://  Secure http URL (default port 443). 
    tfs://    Tacked-on file system URL. 

EXAMPLE

The following example is a macro which, given a file name, uses &stat to check that file file is regular:

define-macro test-file 
    !force set-variable #l0 @1 
    !if &not $status 
        set-variable #l0 @ml04 "File name" 
    !endif 
    !if &not &equ &stat "t" #l4 1 
        ml-write &spr "[%s is not a regular file]" #l0 
        !abort 
    !endif 
!emacro 

test-file "foobar" 

The macro can be passed a file name and aborts if the file is not regular, there by returning the state.

The follow example checks that a file is not empty, this is used by mail-check to test for any incoming mail.

    !if &gre &stat "s" %incoming-mail-box 
        ml-write "[You have new mail]" 
    !endif 

SEE ALSO

Variable Functions, find-file(2), &bstat(4).

Ref: &stat(4) File: m4fil027.4 Date: 2023/02/21

(c) Copyright JASSPA 2026