JavaScript

fs.Stats – get file information

Lean how to query the status of files using Node.js, returning information such as the file type, file owner, access permission file size, number of links, inode number and file birth, access, change and modify times.

You can use any of the three methods to populate the stat structure with the attributes of a file: fs.stat(), fs.lstat(), and fs.fstat(). And their synchronous counterparts are of this type: fs.statSync(), fs.lstatSync(), and fs.fstatSync(). Here are brief descriptions of these methods.

fs.stat() and fs.statSync()

The fs.stat() (and its synchronous counterpart fs.statSync()) method reads information about the file specified in the path parameter. If the named file is a symbolic link, it returns the information about the file that the link points to.

fs.lstat() and fs.lstatSync()

The fs.lstat() (and its synchronous counterpart fs.lstatSync()) method works like the fs.stat() system call, except that if the named file is a symbolic link, the call returns information about the link file and not where it points to.

fs.fstat() and fs.fstatSync()

The fs.fstat() (and its synchronous counterpart fs.fstat()) methods returns information about an open file. It’s generally called a file descriptor.

For more information visit https://nodejs.org/api/fs.html.

Asynchronous example using fs.stat

const fs = require('fs'),
path = 'd:\\ptcl.pdf'

fs.stat(path, (err, stat) => {
 console.log(stat)
})

Synchronous example using fs.statSync

const fs = require('fs'),
path = 'd:\\ptcl.pdf'

const stat = fs.statSync(path)
console.log(stat)

Result

The output yields the following results object on my Windows 10’s command prompt console:

Stats {
 dev: 3803513792,
 mode: 33206,
 nlink: 1,
 uid: 0,
 gid: 0,
 rdev: 0,
 blksize: undefined,
 ino: 281474976744241,
 size: 227700,
 blocks: undefined,
 atimeMs: 1518123325605.2195,
 mtimeMs: 1456549122349.375,
 ctimeMs: 1456549122349.375,
 birthtimeMs: 1518123325605.2195,
 atime: 2018-02-08T20:55:25.605Z,
 mtime: 2016-02-27T04:58:42.349Z,
 ctime: 2016-02-27T04:58:42.349Z,
 birthtime: 2018-02-08T20:55:25.605Z }

How to read fs.Stats information

You can access the properties of fs.Stats object with a simple dot-notation:

const fs = require('fs'),
path = 'd:\\ptcl.pdf'

const stat = fs.statSync(path)
console.log(stat.dev)
//3803513792

You also can use a bracket notation:

console.log(stat['dev'])
//3803513792

Following are the brief description of each fs.Stats properties.

dev

Device id – ID of the device containing the file. This number uniquely identifies the file device.

mode

The mode property hold a lot of useful information, for example:

  • File type (directory, regular file, fifo, socket etc)
  • setuid, setgid and sticky bits are set or not
  • File’s access permissions (e.g. read, write, and execute) for the owner, group and others

nlink

Number of hard links to the file. https://en.wikipedia.org/wiki/Hard_link

uid

The numeric user ID (uid) of the owner of the file.

gid

The numeric group ID (gid) of the file’s owner.

rdev

Device ID if the file is a special file.

blksize

Block size for file system I/O in bytes. This number is the number of bytes in a block of disk unit storage.

ino

File inode number or file id. An inode is a file system data structure that stores information about a file or directory. https://en.wikipedia.org/wiki/Inode

size

The total size in bytes.

blocks

Number of blocks allocated for the file.

atimeMs : Access Time in Milliseconds

The timestamp, in milliseconds, of the last access to the data of the file system entity.

mtimeMs : Modify Time in Milliseconds

The timestamp, represents the file’s last modification time in milliseconds. For example, the last change to file’s content.

ctimeMs : Change Time in Milliseconds

The timestamp, represents the last time the file’s inode was changed in milliseconds. ctimeMs also changes when you change file’s ownership or access permissions.

birthtimeMs : Create Time in Milliseconds

The timestamp, in milliseconds, when a file was first created۔

atime : Access Time

Represents the the last time the data from a file was accessed. For example read by a OS’s process directly or through commands and scripts.

mtime : Modify Time

Represents the file’s last modification time. For example, the last change to file’s content.

ctime : Change Time

Represents the last time the file’s inode was changed. ctime also changes when you change file’s ownership or access permissions.

birthtime : Create Time

Represents when a file was first created, known as “creation time” or “birth time”.