win_stat – Get information about Windows files — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# win_stat – Get information about Windows files

- Synopsis
- Parameters
- See Also
- Examples
- Return Values
- Status

## Synopsis

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

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
checksum_algorithm string | Choices: md5 sha1 ← sha256 sha384 sha512 | Algorithm to determine checksum of file. Will throw an error if the host is unable to use specified algorithm.
follow boolean added in 2.8 | Choices: no ← yes | Whether to follow symlinks or junction points. In the case of `path` pointing to another link, then that will be followed until no more links are found.
get_checksum boolean | Choices: no yes ← | Whether to return a checksum of the file (default sha1)
get_md5 boolean | Choices: no ← yes | Whether to return the checksum sum of the file. Between Ansible 1.9 and Ansible 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=yes` with `checksum_algorithm=md5` to return an md5 hash under the `checksum` return value.
path path / required |  | The full path of the file/object to get the facts of; both forward and back slashes are accepted. aliases: dest, name

## See Also

See also

stat – Retrieve file or file system status
  The official documentation on the stat module.
win_acl – Set file/directory/registry permissions for a system user or group
  The official documentation on the win_acl module.
win_file – Creates, touches or removes files or directories
  The official documentation on the win_file module.
win_owner – Set owner
  The official documentation on the win_owner module.

## 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 module:

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

## Status

- This module is guaranteed to have backward compatible interface changes going forward. [stableinterface]
- This module is maintained by the Ansible Core Team. [core]

### Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

### Authors

- Chris Church (@cchurch)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.