Understanding Stale file handles in Linux

Overview

In this article, we will discuss about the concept of stale file handles and how to avoid it in your application. We will also see some examples on how to use fcntl() function to check if a file handle is valid or not.

The code in this tutorial has been tested on Debian 10.10 (Buster) with GNU Bash 5.0.3. It is POSIX−compliant and should work in any such environment.

What are Stale File Handles?

A file handle can be considered as an integer value that represents the access rights for a particular file. The file system maintains a list of all open files and their corresponding file handles. When you close a file using “close” command, the operating system automatically removes the reference from its internal data structure and updates the file descriptor table (FDT) accordingly. This means that when you try to open another file with the same name, the OS checks whether there is any existing file handle associated with that file name. If yes, then it returns the existing file handle to you. Otherwise, it creates a new file handle and assigns it to the newly opened file.

Index Node

An index node (inodes) is filesystem element, which describes other files. Basically, inodes must be present before any objects like files or directories can be created. Any filesystem object that has an associated inode is called a "filesystem object".

We use the stats (stats) function to display details of a specific text document.

user@baeldung:~$ stat filename
File: filename
Size: 583 Blocks: 8 IO Block: 4096 regular file
Device: 810h/2064d Inode: 666 Links: 1
[...]

The file name references an inode number 666 (the last line).

Who references the file?

File Handle

File handles (file descriptor) are just numbers. They're used to store file descriptions for an indexed system table of open file descriptors.. Unlike file system elements, file handles don't live on or update with the file system. They're instead used by processes to track their open files.

We list this file using the ls (list) commands with the −l (Long Listing Format) flag on the proc filesystem −

user@baeldung:~$ ls -l /proc/1296/fd
total 0
lrwx------ 1 user user 64 Jul 1 10:49 0 -> /dev/pts/1
lrwx------ 1 user user 64 Jul 1 10:49 1 -> /dev/pts/1
lrwx------ 1 user user 64 Jul 1 10:49 2 -> /dev/pts/1
lrwx------ 1 user user 64 Jul 1 10:50 3 -> /home/user/filename

The output indicates that fd3 points to /home/user/filename. Using the dereference command (-L) on fd3 tells us that the inode number for that path is 2.

user@baeldung:~$ stat -L /proc/1296/fd/3
File: /proc/1296/fd/3
Size: 583 Blocks: 8 IO Block: 4096 regular file
Device: 810h/2064d Inode: 666 Links: 1
[...]

A process may refer to a particular inode by using its name (e.g., /tmp/foo), but if the inode has been renamed, then the process won't be able to access the.

Stale File Handles

Once an inodes isn't referenced or linked to anymore, it becomes free for future use.

At this stage, the related files' open handle points to an invalid or different inode number than before. It is almost impossible for the system to reuse the same inode number again.

The result of an unsuccessful upload comes up in different ways, but one common way is ESTALE 116 with a message Stale file handle.

user@baeldung:~$ cd /mounted
-bash: cd: /mounted: Stale file handle

If the process doesn't successfully complete, it might just fail silently without producing any output or claiming missing files.

There is usually just one standard solution for this problem.

Resolve Stale File Handles

When a process opens a stale handle, it gets a new one. If the file already has an inodes, then updating its inodes will update its file description. Most often, the process has to be done internally. If not, we might have to start again.

With mounting shared directories, this solution may not be trivial.

When using NFS or CIFs, the most common scenario where stale files are not refreshed is when they're used for mounting shared folders. Protocol implementations often lack standardized caching and file handle coordination. Such scenarios often require remounts (possibly with different settings) or even server processes restarted. Both of these actions could cause some down time.

Summary

We looked at the chain of reference that a particular piece of software uses to access files. We saw how that chain can do break.

We've shown how to fix stale file handles in different situations where they occur.