win_stat – Get information about Windows files

From Get docs
Ansible/docs/2.8/modules/win stat module


win_stat – Get information about Windows files

Synopsis

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

Parameters

Parameter Choices/Defaults Comments

checksum_algorithm

string

added in 2.3

  • 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

  • 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

added in 2.1

  • no
  • yes

Whether to return a checksum of the file (default sha1)

get_md5

boolean

  • 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

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.


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