FORMATS

Format strings are similar to printf(3) formats in that they contain character data, which is simply output, interspersed with data conversions which start with %, are then followed by a sequence of formatting characters, and end in a character that selects the datum, the field of the struct stat, or other data, which is to be formatted. If the % is immediately followed by one of n, t, %, or @, then a newline character, a tab character, a percent character, or the current file number in the argument list is printed. Otherwise the string is examined for the following:

Any of the following optional flags in any order:

#

Selects an alternate output form for string, octal and hexadecimal output. String output will be encoded in vis(3) style. Octal output will have a leading zero. Non-zero hexadecimal output will have ‘0x’ prepended to it.

+

Asserts that a sign indicating whether a number is positive or negative should always be printed. Non-negative numbers are not usually printed with a sign.

-

Aligns string output to the left of the field, instead of to the right.

0

Sets the fill character for left padding to the 0 character, instead of a space.

space

Reserves a space at the front of non-negative signed output fields. A ‘+’ overrides a space if both are used.

Then followed by the following fields in the following order:

size

An optional decimal digit string specifying the minimum field width. Note that a leading zero is treated as the ‘0’ flag (above), subsequent embedded zeroes are part of the size.

prec

An optional precision composed of a decimal point ‘.’ and a decimal digit string that indicates the maximum string length, the number of digits to appear after the decimal point in floating point output, or the minimum number of digits to appear in other numeric output.

fmt

An optional output format specifier which is one of D, O, U, X, F, or S. These represent signed decimal output, octal output, unsigned decimal output, hexadecimal output, floating point output, and string output, respectively. Some output formats do not apply to all fields. Floating point output only applies to timespec fields (the a, m, and c fields).

The special output format specifier S may be used to indicate that the output, if applicable, should be in string format. May be used in combination with the following field specifiers:

a, m, c

Display date in strftime(3) format with the extension that ‘%f’ prints nanoseconds if available.

d, r

Display actual device name.

f

Display the flags of file as in ls -ldo.

g, u

Display group or user name.

p

Display the mode of file symbolically, as in ls -lTd.

N

Displays the name of file.

T

Displays the type of file.

R, Y

Insert a ‘ -> ’ into the output. Note that the default output formats for Y and R are strings, if S is specified explicitly, these four characters are prepended.

sub

An optional sub field specifier: high, middle, or low. Only applies to the d, N, p, r, T, and z output field specifiers. It can be one of the following:

H

“High” subfield of datum:

d, r

Major number for devices

N

Directory path of the file, similar to what dirname(1) would show

p

“User” bits from the string form of permissions, or the file “type” bits from the numeric forms

T

The long output form of file type

z

File size, rounded to the nearest gigabyte

M

“Middle” subfield of datum:

p

The “group” bits from the string form of permissions, or the “suid”, “sgid”, and “sticky” bits from the numeric forms

z

File size, rounded to the nearest megabyte

L

“Low” subfield of datum:

d, r

Minor number for devices

N

Base filename of the file, similar to what basename(1) would show

p

The “other” bits from the string form of permissions, or the “user”, “group”, and “other” bits from the numeric forms

T

The ls -F style output character for file type (the use of L here is optional)

z

File size, rounded to the nearest kilobyte

datum

A required field specifier, ending the conversion specification, being one of the following:

d

Device upon which file resides (st_dev).

i

file's inode number (st_ino).

p

File type and permissions (st_mode).

l

Number of hard links to file (st_nlink).

u, g

User-id and group-id of file's owner (st_uid, st_gid).

r

Device number for character and block device special files (st_rdev).

a, m, c, B

The time file was last accessed or modified, or when its inode was last changed, or the birth time of the inode (st_atime, st_mtime, st_ctime, st_birthtime).

z

The size of file in bytes (st_size).

b

Number of blocks allocated for file (st_blocks).

k

Optimal file system I/O operation block size (st_blksize).

f

User defined flags for file (st_flags).

v

Inode generation number (st_gen).

The following five field specifiers are not drawn directly from the data in struct stat, but are:

N

The name of the file.

R

The absolute pathname corresponding to the file.

T

The file type, either as in ls -F or in a more descriptive form if the sub field specifier H is given.

Y

The target of a symbolic link.

Z

Expands to “major,minor” (that is, ‘%Hr,%-Lr’) for character or block special devices, and gives size output (‘%z’) for all other file types. A specified field width applies to the overall result (approximately half each for the two device file sub-fields), but precision, output format, and flags are used separately for each conversion made (but note the ‘-’ in the ‘%-Lr’ conversion.)

Only the ‘%’ and the datum (field specifier) are required. Most field specifiers default to U as an output format, with the exception of p which defaults to O; a, m, and c which default to D; and Y, T, R, and N, which default to S.