umask()

Introduction

In PHP, the umask() function sets the default permissions for newly created files and directories. It is a useful tool for managing file access in your scripts. In this article, we will cover everything you need to know about umask(), including its syntax, parameters, and practical examples.

Understanding the umask() Function

The umask (user file-creation mode mask) is a set of permission bits that the operating system removes from the default permissions whenever a process creates a file or directory. The umask() function reads or changes that mask for the current PHP process.

• It accepts an optional $mask parameter. If called without arguments, it returns the current mask without changing anything.
• When a mask is provided, it becomes the new mask and the function returns the previous mask value.
• The mask applies to the whole PHP process, not just the current script — so changing it can affect later file operations in the same request.

PHP starts from the system's base permissions — typically 0666 for files (read + write, no execute) and 0777 for directories — and computes the final permissions with a bitwise AND against the inverted mask:

final = base & ~mask

How the Mask Math Works

The mask clears the bits it contains. Each octal digit corresponds to owner, group, and others, and each digit is a sum of read (4), write (2), and execute (1).

With umask(022):

files:        0666 & ~022 = 0666 & 0755 = 0644   (rw-r--r--)
directories:  0777 & ~022 = 0777 & 0755 = 0755   (rwxr-xr-x)

The 2 in positions for group and others removes the write bit, so group and others can read but not write. A stricter umask(077) would clear all group/other permissions, yielding 0600 for files and 0700 for directories — files only the owner can access.

Syntax of the umask() Function

The syntax of the umask() function is as follows:

umask($mask);

Here, $mask is the new mask. It must be specified in octal notation, so always write it with a leading zero (e.g., 022). Writing 22 would be interpreted as the decimal value 22, not the octal mask you intended.

Examples of Using umask()

Example 1: Setting the Default Permissions for New Files

<?php

umask(022);
$file_handle = fopen('example.txt', 'w');
fclose($file_handle);
echo 'File permissions: ' . decoct(fileperms('example.txt') & 0777);
unlink('example.txt');

Output:

File permissions: 644

This sets the mask to 022, then creates example.txt. The base file permission 0666 minus the masked write bits gives 0644. The fileperms() call reads the actual permissions back, and & 0777 strips the file-type bits so decoct() prints just the access part.

Example 2: Reading and Restoring the Current Mask

Because the mask affects the whole process, a well-behaved function should restore it when done. Calling umask() with no argument returns the current value without changing it.

<?php

// Save the current mask, then apply a strict one
$old = umask(077);

$dir = sys_get_temp_dir() . '/private';
mkdir($dir);
echo 'Dir permissions: ' . decoct(fileperms($dir) & 0777) . "\n";

// Restore the original mask
umask($old);
echo 'Restored mask: ' . decoct(umask()) . "\n";

rmdir($dir);

Output:

Dir permissions: 700
Restored mask: 22

Here umask(077) clears every group and other bit, so the new directory gets 0777 & ~077 = 0700 — accessible only by the owner. Saving the previous mask in $old and passing it back to umask() leaves the process in the state it started in.

Common Pitfalls

• umask() is process-wide. In a long-running context (FPM workers, CLI daemons) one script's umask() call leaks into later requests on the same worker. Always restore the previous value as in Example 2.
• It only affects creation. Existing files are unchanged; use chmod() to alter permissions after the fact.
• The OS caps the result. umask() can only remove bits. It cannot grant the execute bit to a regular file, since the base mode for files is already 0666.
• Forgetting the leading zero. umask(22) and umask(022) mean different things — the first is decimal, the second is octal.

Related Functions

• chmod() — change permissions on an existing file or directory.
• fileperms() — read a file's current permission bits.
• mkdir() — create a directory (its mode argument is also filtered by the umask).
• fopen() — open or create a file.

Conclusion

The umask() function controls which permission bits are stripped from newly created files and directories. Remember that it works by removing bits (base & ~mask), applies process-wide, and only affects new creations. When you change it inside a function, save and restore the previous value to avoid surprising later code.

Practice