8.4.32 stat command (outputs the statuses of files and directories to the standard output)
Syntax
stat [-L] [-c format] [-t] path-name ...
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.
Arguments
-L
- --dereference
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.
Return codes
Return code |
Meaning |
---|---|
0 |
Normal termination |
1 or greater |
Error termination |
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. |
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
%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.
If the command fails to get a reference file name, the command outputs a warning message to the standard error output, and then continues the subsequent processing without displaying the reference file name.
%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
YYYY: Calendar year
MM: Month
DD: Date
hh: Hour
mm: Minute
ss: Second
nnnnnnnnn: Date and time less than one second. 000000000 is always output.
+/-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 |
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) |
Notes
-
In Windows, a file other than normal file, directory or symbolic link 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.
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 [-L] [-c format] [-t] file ...