stat command (outputs the statuses of files and directories to the standard output)

Organization of this page

Format
Description
Arguments
Return codes
Display formats
Notes
Examples

Format

(Windows only) stat [-c format] [-t] path-name ...
(UNIX only)   stat [-L] [-c format] [-t] path-name ...

To Page Top

Description

This command outputs file or directory statuses to the standard output. If a symbolic link file is specified for path-name, the command displays the status of the symbolic link file without using the link.

To Page Top

Arguments

-L

--dereference

(UNIX only)

Specifies that if a symbolic link file is specified for path-name, the command is to display the status of the file or directory at the link destination.

-c format

--format=format

Specifies the format in which the status of a file or directory is to be displayed . For format, you can specify a format specification code and any character string. For details about the display formats and format specification codes when this option is specified, see Unique display format in Display formats. If an unsupported format specification code is specified, the command outputs a warning message to the standard error output and a question mark (?) to the standard output, and then resumes the subsequent processing.

If this option is specified together with the -t option, this option takes effect.

-t

--terse

Specifies that the information is to be displayed in the concise format. For details about the concise display format, see Concise display format in Display formats.

path-name

Specifies the name of a file or a directory whose status is to be displayed.

If multiple path names are specified, file or directory statuses are displayed vertically. If the command is executed with multiple path names specified and the status display fails even for one of the files or directories, the command terminates with return code 1.

To Page Top

Return codes

Return code	Meaning
`0`	Normal termination
`1` or greater	Error termination

To Page Top

Display formats

The three file information display formats are the normal display format, the concise display format, and the unique display format. The display format to be used depends on the options specification.

Normal display format

This is the display format used when no option is specified. The following file information is displayed with the indicated labels:

Output information	Label
Quoted file name For a symbolic link, the reference target of the symbolic link is also displayed. (UNIX only)	`File:`
Total size	`Size:`
Number of allocated blocks	`Blocks:`
Optimum block size for file system I/O operations	`IO` `Block:`
File type For details about the information that is displayed, see Information displayed as file types in Display formats.	`-`
Device number This information is displayed in the format `device-number-in-hexadecimal-h/device-number-in-decimal-d`. Nothing is displayed for non-device files.	`Device:`
Inode number	`Inode:`
Number of hard links	`Links:`
Device file type This information is displayed in the format `major-device-number,minor-device-number`. Nothing is displayed for non-device files.	`Device` `type:`
Permissions This information is displayed in the format `permissions-in-octal/permissions-character-string`.	`Access:`
Owner's user information This information is displayed in the format `owner's-user-ID/owner's-user-name`.	`Uid:`
Owner's group information This information is displayed in the format `owner's-group-ID/owner's-group-name`.	`Gid:`
File's most recent access date and time	`Access:`
File's most recent modification date and time	`Modify:`
Most recent date and time file information was changed	`Change:`

Legend:: -: Displayed without a label.

Concise display format

This is the display format used when the -t option is specified. The following information is displayed sequentially separated by the space.

File name
Total size
Number of allocated blocks
raw mode in hexadecimal
Owner's user ID
Owner's group ID
Device number in hexadecimal
Inode number
Number of hard links
Major device number
Minor device number
File's most recent access date and time (number of seconds since the epoch)
File's most recent modification date and time (number of seconds since the epoch)
Most recent date and time file information was changed (number of seconds since the epoch)
Optimum block size for file system I/O operations

Unique display format

This is the display format used when the -c option is specified. You can specify a unique display format by combining format specification codes and any character strings. Also, format specification code % can be followed by a flag character, field width, and precision.

Format specification codes

The following table lists and describes the supported format specification codes:

Format specification code	Meaning
`%a`	Permissions in octal In Windows, only the owner's permissions are displayed.
`%A`	Permissions character string In Windows, only the owner's permissions are displayed.
`%b`	Number of allocated blocks In Windows, `0` is always displayed.
`%B`	Size of one block (bytes) In Windows, `0` is always displayed.
`%d`	Device number in decimal In Windows, a drive number is displayed, but the display varies in the following cases: For paths whose full path has no colon (`:`) after the drive letter The command displays `-` as the device number and then resumes the subsequent processing. If the device number acquisition processing results in an error The command outputs a warning message to the standard error output, displays a question mark (`?`) as the device number, and then resumes the subsequent processing.
`%D`	Device number in hexadecimal In Windows, a drive number is displayed, but the display varies in the following cases: For paths whose full path has no colon (`:`) after the drive letter The command displays `-` as the device number and then resumes the subsequent processing. If the device number acquisition processing results in an error The command outputs a warning message to the standard error output, displays a question mark (`?`) as the device number, and then resumes the subsequent processing.
`%f`	`raw` mode in hexadecimal In Windows, only the owner's permissions are displayed.
`%F`	File type For details about the information that is displayed, see Information displayed as file types in Display formats.
`%g`	Owner's group ID In Windows, `0` is always displayed.
`%G`	Owner's group name In Windows, an ellipsis (`...`) is always displayed. In UNIX, if the owner's group name cannot be acquired, the command displays the owner's group ID and then resumes the subsequent processing.
`%h`	Number of hard links In Windows, `0` is always displayed.
`%i`	Inode number In Windows, `0` is always displayed.
`%n`	File name
`%N`	File name enclosed in quotation marks For a symbolic link, the name of the referenced file is also displayed. In Windows, the name of the referenced file is not displayed even for a symbolic link. In UNIX, if acquisition of the name of the referenced file fails, the command outputs a warning message to the standard error output and then resumes the subsequent processing without displaying the name of the referenced file.
`%o`	Optimum block size for file system I/O operations In Windows, `0` is always displayed.
`%s`	Total size (bytes) In Windows, `0` is always displayed as the total size of directories. In UNIX, `0` is always displayed as the total size of device files.
`%t`	Major device number in hexadecimal In Windows, `0` is always displayed.
`%T`	Minor device number in hexadecimal In Windows, `0` is always displayed.
`%u`	Owner's user ID In Windows, `0` is always displayed.
`%U`	Owner's user name In Windows, if the owner's user name cannot be acquired, the command displays an ellipsis (`...`), and then resumes the subsequent processing. In UNIX, if the owner's user name cannot be acquired, the command displays the owner's user ID, and then resumes the subsequent processing.
`%x`	File's most recent access date and time In Windows, the file's most recent modification date and time is displayed. If the command fails to display the file's most recent access date and time, the command outputs a warning message to the standard error output, displays a question mark (`?`) as the file's most recent access date and time, and then resumes the subsequent processing.
`%X`	File's most recent access date and time Number of seconds from the epoch (UTC January 1, 1970, 00:00:00) to the file's most recent access date and time. In Windows, the file's most recent modification date and time is displayed.
`%y`	File's most recent modification date and time^# If the command fails to display the file's most recent modification date and time, the command outputs a warning message to the standard error output, displays a question mark (`?`) as the file's most recent modification date and time, and then resumes the subsequent processing.
`%Y`	Number of seconds from the epoch (UTC January 1, 1970, 00:00:00) to the file's most recent modification date and time
`%z`	Most recent date and time file information was changed^# In Windows, the file's most recent modification date and time is displayed. If the command fails to display the most recent date and time file information was changed, the command outputs a warning message to the standard error output, displays a question mark (`?`) as the most recent date and time file information was changed, and then resumes the subsequent processing.
`%Z`	Number of seconds from the epoch (UTC January 1, 1970, 00:00:00) to the most recent date and time the file was changed. In Windows, the file's most recent modification date and time is displayed.
`%%`	Percent symbol (`%`)

#

The following format is used for display of file's most recent access date and time, file's most recent modification date and time, and most recent date and time file information was changed:

YYYY-MM-DD hh:mm:ss.nnnnnnnnn +/-hhmm

[Figure] YYYY: Calendar year

[Figure] MM: Month

[Figure] DD: Date

[Figure] hh: Hour

[Figure] mm: Minute

[Figure] ss: Second

[Figure] nnnnnnnnn: Date and time less than one second. 000000000 is always output.

[Figure] +/-hhmm: Time zone (time differential from UTC)

Flag characters

You can specify (or omit) the following flag characters following the % format specification code:

Flag character	Description
`#`	Prefixes with `0` an octal number other than 0. Prefixes with `0x` a hexadecimal number other than 0.
`-`	Left-aligns the output character strings in fields.
`+`	Always displays a symbol (`+` or `-`) indicating a positive or negative numeric value. This specification is ignored for file information that is defined as unsigned integers.
space	Displays a space before a positive number for file information that is defined as signed integers. If this flag character is specified together with `+`, `+` takes effect.
`0`	Pads the leading part of fields with zeros, not spaces.

Field width

You can define a minimum field width by specifying a numeric value following the % format specification code or flag character. The permitted range for field width is from 0 to 2147483647. The field width can be omitted.
Precision

You can define a period (.) and one of the numeric values listed below following the % format specification code or flag character. The precision range is from 0 to 2147483647 in UNIX and from 0 to 512 in Windows. The precision can be omitted.
- If the file information is a character string
  
  The maximum length to be displayed is defined.
- If the file information is a numeric value
  
  The minimum number of digits is defined.

Information displayed as file types

The following table lists the file types that are displayed and their meanings:

File type	Meaning
`regular` `file`	Regular file
`directory`	Directory
`symbolic` `link`	Symbolic link (UNIX only)
`fifo`	FIFO (UNIX only)
`socket`	Socket (UNIX only)
`block` `special` `file`	Block special file (UNIX only)
`character` `special` `file`	Character special file (UNIX only)
`unknown` `file`	Unknown file (other than the above) (UNIX only)

To Page Top

Notes

In Windows, a file other than a normal file or directory is handled as a regular file or directory.

In UNIX, a file other than a regular file, directory, symbolic link, FIFO, socket, block special file, or character special file is handled as an unknown file.
In Windows, the time zone set in the Date and Time control panel is used to display the date and time. The value of the TZ environment variable has no effect.

Note that the value of the TZ environment variable and the time zone set in the Date and Time control panel are used to display the time zone. For this reason, you must ensure that the value of the TZ environment variable and the time zone set in the Date and Time control panel are the same. If they differ, the correct time zone will not be displayed for a file's most recent access date and time, a file's most recent modification date and time, and the most recent date and time file information was updated.
In UNIX, the default block size is 512 bytes. You can change the block size with the BLOCKSIZE environment variable.

The permitted value range for the BLOCKSIZE environment variable is from 512 to 1G (1,024 1,024 1,024). If the specified value is outside this range, the command handles it as described below, outputs a warning message to the standard error output, and then performs the subsequent processing:
- If a value smaller than 512 is specified in the BLOCKSIZE environment variable
  
  The block size is set to 512 bytes.
- If a value greater than 1G (1,024 1,024 1,024) is specified in the BLOCKSIZE environment variable
  
  The block size is set to 1G (1,024 1,024 1,024).
If you use the BLOCKSIZE environment variable to change the block size, specify a multiple of 512. If the specified value is not a multiple of 512, the remainder will be discarded. For example, if a size of 1,500 bytes is defined, the block size will be treated as being 1,024 bytes.

You can specify following the numeric value a size character indicating a multiple, such as G (1,024 1,024 1,024), M (1,024 1,024), or K (1,024). If any value other than a numeric value and size character is specified, the command will assume 512 bytes as the block size, output a warning message to the standard error output, and then resume the subsequent processing.
In Solaris, the total number of blocks including indirect blocks is displayed as the number of allocated blocks for files in a directory. If there are hard-linked files, the number of allocated blocks will not display correctly.

To Page Top

Examples

Display a file's status in the normal display format.

In Windows:

C:\TEMP>%ADSH_OSCMD_DIR%\stat .\test.txt
  File: `.\test.txt'
  Size: 7               Blocks: 0          IO Block: 0      regular file
Device: 0003h/00003d    Inode: 0           Links: 1
Access: (0600/-rw-------)  Uid: (    0/   user1)   Gid: (    0/     ...)
Access: 2014-02-20 10:31:28.000000000 +0900
Modify: 2014-02-20 10:31:33.000000000 +0900
Change: 2014-02-20 10:31:28.000000000 +0900

In UNIX:

$ stat ./test.txt
  File: `./test.txt'
  Size: 4               Blocks: 8          IO Block: 4096   regular file
Device: fd00h/64768d    Inode: 688407      Links: 2
Access: (0644/-rw-r--r--)  Uid: (  501/   user1)   Gid: (  502/  group1)
Access: 2014-02-11 18:35:52.000000000 +0900
Modify: 2014-02-11 18:35:52.000000000 +0900
Change: 2014-02-18 16:08:39.000000000 +0900

Display a file's size only.

C:\TEMP>%ADSH_OSCMD_DIR%\stat -c %s .\test.txt
7

Display the statuses of multiple files.

C:\TEMP>%ADSH_OSCMD_DIR%\stat .\test.txt .\test1.txt
  File: `.\test.txt'
  Size: 7               Blocks: 0          IO Block: 0      regular file
Device: 0003h/00003d    Inode: 0           Links: 1
Access: (0600/-rw-------)  Uid: (    0/   user1)   Gid: (    0/     ...)
Access: 2014-02-20 10:31:28.000000000 +0900
Modify: 2014-02-20 10:31:33.000000000 +0900
Change: 2014-02-20 10:31:28.000000000 +0900
  File: '.\test1.txt'
  Size: 7               Blocks: 0          IO Block: 0      regular file
Device: 0003h/00003d    Inode: 0           Links: 1
Access: (0600/-rw-------)  Uid: (    0/   user1)   Gid: (    0/     ...)
Access: 2014-02-20 14:34:01.000000000 +0900
Modify: 2014-02-20 14:34:01.000000000 +0900
Change: 2014-02-20 14:34:01.000000000 +0900

Display a file's status in the unique display format.

C:\TEMP>%ADSH_OSCMD_DIR%\stat -c "Filename : %n" .\test.txt
Filename : .\test.txt

Display option error messages:

This message might vary depending on the platform used to execute the command. The following is an example for Windows:
```
C:\TEMP>%ADSH_OSCMD_DIR%\stat -z
stat: illegal option -- z
usage: stat [-c format] [-t] file ...
```

To Page Top