# &stat(4)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

## 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.

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.
        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.

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.

Note that a URL type is determined from the file name, e.g. http://..., and its existence is not verified.

w

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

x

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

## 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).

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12

</HMTL>