Finding Properties of Files and Directories

Once you have obtained a file or directory name, you can ask about the properties of that file or directory. The set of properties available is inherently operating-system-dependent. This section describes the facilities currently available under UNIX and the restrictions in the Windows version.

Properties fall into several classes. The current classes are


boolean
having values true and false
integer
having non-negative integer values

In the Windows version no _id information, such as user_id, is obtained.

who
(UNIX only) values are subsequences of [user,group,other] -- that is, the order of the elements must be preserved. Subsets will not do -- [other,user] is not a possible value.
date
values are date(Year, Month, Day) terms. The arguments are this way round so you can use them for sorting.
time
values are date(Year, Month, Day, Hour, Minute, Second) terms, with Hour on a 24-hour clock. The arguments are in this order so you can use them for sorting. The times given are local times, not GMT times. See ctime(3).
user
(UNIX only) values are user names
group
(UNIX only) values are group names

The properties, with their types, are 

     readable        : boolean
     writable        : boolean
     executable      : boolean       file only
     searchable      : boolean       directory only
     set_user_id     : boolean       file only
     set_group_id    : boolean       file only
     save_text       : boolean       file only
     only_one_link   : boolean       file only
     who_can_read    : who
     who_can_write   : who
     who_can_execute : who           file only
     who_can_search  : who           directory only
     access_date     : date
     modify_date     : date
     create_date     : date
     access_time     : time
     modify_time     : time
     create_time     : time
     owner_user_name : user
     owner_group_name: group
     owner_user_id   : integer
     owner_group_id  : integer
     number_of_links : integer       file only
     size_in_bytes   : integer       file only
     size_in_blocks  : integer       file only
     block_size      : integer       file only

The properties readable, writable, executable, and searchable ask the question "can this process do such-and-such to the file". For more information, see access(2). For more information on the other properties, see stat(2).

The basic routine for determining the properties of files is


file_property(+File, ?Property, ?Value)
file_property/3 is true when File is the name of a visible regular file, Property is one of the properties listed in the table above, other than those specific to directories, and Value is the actual value of Property for that File. File must be specified; there may be tens of thousands of files with a particular attribute! However, you can enumerate all the properties of a given File (by leaving Property uninstantiated) if you like.

file_property/3 has the following variant:


file_property(+File, ?Property)
is only allowed when Property is a boolean property, and is otherwise equivalent to the call 
          file_property(File, Property, true)

(Note that if there is a user with login name true, file_property(F,owner_user_name,true) is possible, but file_property(F,owner_user_name) is not; the Property really must be a boolean property, not just have true as its value.) In particular, a quick way to check whether File names a file that this process can read is to ask 

          file_property(File, readable)

See also can_open_file/3 in library(files). Note that 

          file_property(File, writable)

asks whether a writable File already exists; if you want to know whether open(File, write, Stream) will be allowed, use can_open_file/3 (see lib-ofi).

To match these two predicates, which access properties of files, there are two predicates for asking about the properties of directories: