Documentation

win_stat - returns information about a Windows file

New in version 1.7.

Synopsis

  • Returns information about a Windows file.
  • For non-Windows targets, use the module_docs/stat module instead.

Options

parameter
required
default
choices
comments
path
yes
The full path of the file/object to get the facts of; both forward and back slashes are accepted.
get_md5
no
no
  • yes
  • no
Whether to return the checksum sum of the file. Between Ansible 1.9 and 2.2 this is no longer an MD5, but a SHA1 instead. As of Ansible 2.3 this is back to an MD5. Will return None if host is unable to use specified algorithm.
The default of this option changed from yes to no in Ansible 2.5 and will be removed altogether in Ansible 2.9.
Use get_checksum=true with checksum_algorithm=md5 to return an md5 hash under the checksum return value.
get_checksum
(added in 2.1)
no
yes
  • yes
  • no
Whether to return a checksum of the file (default sha1)
checksum_algorithm
(added in 2.3)
no
sha1
  • md5
  • sha1
  • sha256
  • sha384
  • sha512
Algorithm to determine checksum of file. Will throw an error if the host is unable to use specified algorithm.

Examples

- name: Obtain information about a file
  win_stat:
    path: C:\foo.ini
  register: file_info

- name: Obtain information about a folder
  win_stat:
    path: C:\bar
  register: folder_info

- name: Get MD5 checksum of a file
  win_stat:
    path: C:\foo.ini
    get_checksum: yes
    checksum_algorithm: md5
  register: md5_checksum

- debug:
    var: md5_checksum.stat.checksum

- name: Get SHA1 checksum of file
  win_stat:
    path: C:\foo.ini
    get_checksum: yes
  register: sha1_checksum

- debug:
    var: sha1_checksum.stat.checksum

- name: Get SHA256 checksum of file
  win_stat:
    path: C:\foo.ini
    get_checksum: yes
    checksum_algorithm: sha256
  register: sha256_checksum

- debug:
    var: sha256_checksum.stat.checksum

Return Values

Common return values are documented here, the following are the fields unique to this {{plugin_type}}:

name
description
returned
type
sample
stat
dictionary containing all the stat data
success
complex
exists
If the path exists or not
success
boolean
True
lnk_target
Target of the symlink. Note that relative paths remain relative
success, path exists and the path is a symbolic link or junction point
string
..\link
lastwritetime
The last modification time of the file represented in seconds since epoch
success, path exists
float
1477984205.15
creationtime
The create time of the file represented in seconds since epoch
success, path exists
float
1477984205.15
lastaccesstime
The last access time of the file represented in seconds since epoch
success, path exists
float
1477984205.15
nlink
Number of links to the file (hard links)
success, path exists
int
1
owner
The owner of the file
success, path exists
string
BUILTIN\Administrators
path
The full absolute path to the file
success, path exists, file exists
string
C:\foo.ini
isarchive
If the path is ready for archiving or not
success, path exists
boolean
True
ishidden
If the path is hidden or not
success, path exists
boolean
True
lnk_source
Target of the symlink normalized for the remote filesystem
success, path exists and the path is a symbolic link or junction point
string
C:\temp\link
size
The size in bytes of a file or folder
success, path exists, file is not a link
int
1024
isdir
If the path is a directory or not
success, path exists
boolean
True
extension
The extension of the file at path
success, path exists, path is a file
string
.ps1
isreadonly
If the path is read only or not
success, path exists
boolean
True
sharename
The name of share if folder is shared
success, path exists, file is a directory and isshared == True
string
file-share
isjunction
If the path is a junction point or not
success, path exists
boolean
True
filename
The name of the file (without path)
success, path exists, path is a file
string
isreg
If the path is a regular file
success, path exists
boolean
True
hlnk_targets
List of other files pointing to the same file (hard links), excludes the current file
success, path exists
list
['C:\\temp\\file.txt', 'C:\\Windows\\update.log']
checksum
The checksum of a file based on checksum_algorithm specified
success, path exist, path is a file, get_checksum == True checksum_algorithm specified is supported
string
09cb79e8fc7453c84a07f644e441fd81623b7f98
islnk
If the path is a symbolic link or not
success, path exists
boolean
True
attributes
Attributes of the file at path in raw form
success, path exists
string
Archive, Hidden
isshared
If the path is shared or not
success, path exists
boolean
True
md5
The MD5 checksum of a file (Between Ansible 1.9 and 2.2 this was returned as a SHA1 hash), will be removed in 2.9
success, path exist, path is a file, get_md5 == True
string
09cb79e8fc7453c84a07f644e441fd81623b7f98
changed
Whether anything was changed
always
boolean
True


Notes

Note

Author

  • Chris Church (@cchurch)

Status

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.

Maintenance Info

For more information about Red Hat’s support of this module, please refer to this Knowledge Base article

If you want to help with development, please read Community Information & Contributing, Testing Ansible and Developing Modules.