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 stat module instead.

Options

parameter required default choices comments
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.
get_checksum
(added in 2.1)
 no True
Whether to return a checksum of the file (default sha1)
get_md5
 no True
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.
This option is deprecated in Ansible 2.3 and is replaced with checksum_algorithm=md5.
path
 yes
The full path of the file/object to get the facts of; both forward and back slashes are accepted.

Examples

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

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

# 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

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

- debug:
    var: sha1_checksum.stat.checksum

# 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 Return Values, the following are the fields unique to this module:

name description returned type sample
changed
Whether anything was changed
 always boolean True
stat
dictionary containing all the stat data
 success complex
contains:
name description returned type sample
exists
if the path exists or not
 success boolean True
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
isshared
if the path is shared or not
 success, path exists boolean True
lastaccesstime
the last access time of the file represented in seconds since epoch
 success, path exists float 1477984205.15
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
the target of the symbolic link, will return null if not a link or the link is broken
 string C:\temp
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
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
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 junction or not
 success, path exists boolean True
attributes
attributes of the file at path in raw form
 success, path exists string Archive, Hidden
md5
The MD5 checksum of a file (Between Ansible 1.9 and 2.2 this was returned as a SHA1 hash)
 success, path exist, path is a file, get_md5 == True, md5 is supported string 09cb79e8fc7453c84a07f644e441fd81623b7f98

Notes

Note

  • For non-Windows targets, use the stat module instead.

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 this support of this module, please refer to this knowledge base article<https://access.redhat.com/articles/rhel-top-support-policies>

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/win_stat_module.html