Filesystem Modes

A filesystem entry has an integer mode that specifies:

• Permissions.

• Special bits.

• File type.

The mode is most often seen as an octal-format integer:

• Rightmost three digits encode the permissions.

• Next digit encodes the special bits.

• Leftmost two digits encode the file type.

On this page, we show a mode using format '%06o, which displays the mode as a 6-digit octal number:

'%06o' % File.stat('/etc/passwd').mode # => "100644"

Getting a Mode

You can use method File::Stat#mode to get the mode of a filesystem entry.

Each of these methods returns a File::Stat object for a given filesystem entry. The first three follow symbolic links; the others don’t:

• File::stat.

• IO#stat.

• Pathname#stat.

• File::lstat.

• File#lstat.

• Pathname#lstat.

Once you have the File::Stat object, you can fetch the mode for the entry:

'%06o' % File.stat('/etc').mode        # => "040755"
'%06o' % File.stat('/etc/passwd').mode # => "100644"

Setting a Mode

The mode for an entry is initialized when the entry is created:

filepath = '/tmp/t.txt'
File.write(filepath, 'foo')
'%06o' % File.stat(filepath).mode # => "100664"
File.delete(filepath)             # Clean up.
dirpath = '/tmp/bar'
Dir.mkdir(dirpath)
'%06o' % File.stat(dirpath).mode  # => "040775"
Dir.rmdir(dirpath)                # Clean up.

You can use one of these methods to change the permissions and special bits (but not the file type):

• File#chmod.

• File::chmod.

• File::lchmod (does not follow symbolic links).

• FileUtils#chmod.

• FileUtils#chmod_R.

• FileUtils::chmod.

• FileUtils::chmod_R.

• Pathname#chmod.

• Pathname#lchmod (does not follow symbolic links).

The actual effects of these methods is filesystem-dependent.

Permissions

A filesystem entry has permissions:

• Read: whether the file or directory may be read, and by what processes.

• Write: whether the file of directory may be written, and by what processes.

• Execute/search:

  • File: whether the file may be executed, and by what processes.

  • Directory: whether the directory may be searched, and by what processes.

Executable Files

On Windows, a file is executable if its path has one of these file extensions: .bat, .cmd, .com, or .exe:

File.executable?('win32/rtname.cmd') # => true
File.executable?('win32/rtname')     # => false
File.executable?('win32/nosuch.cmd') # => false

On other systems, a file is executable if it has the execute/search permission for the effective user and group id of the current process:

File.executable?('/bin/ruby')   # => true   # Executable file.
File.executable?('/etc')        # => true   # Searchable directory.
File.executable?('/etc/passwd') # => false  # Non-executable file.
File.executable?('nosuch')      # => false  # Non-existent.

Setting Permissions

For a method that actually creates a file in the underlying filesystem (as opposed to merely creating a File object), permissions may be specified; the permissions may also be changed:

filepath = '/tmp/t.tmp'
File.write(filepath, 'foo')
'%06o' % File.stat(filepath).mode # => "100664"
File.chmod(0o775, filepath)
'%06o' % File.stat(filepath).mode # => "100775"
File.delete(filepath)             # Clean up.

For a method that actually creates a directory in the underlying filesystem (as opposed to merely creating a Dir object), permissions may be specified; the permissions may also be changed:

dirpath = '/tmp/dir'
Dir.mkdir(dirpath)
'%06o' % File.stat(dirpath).mode # => "040775"
File.chmod(0o644, dirpath)
'%06o' % File.stat(dirpath).mode # => "040644"
Dir.rmdir(dirpath)               # Clean up.

On non-Posix operating systems, permissions may include only read-only or read-write, in which case, the remaining permission will resemble typical values. On Windows, for instance, the default permissions are 0644; The only change that can be made is to make the file read-only, which is reported as 0444.

Directory and File Permissions

Permissions for directories and files include read and write permissions.

The permissions in this table do not involve execute/search, and so apply similarly to a directory or a file.

File Permissions

Permissions for a file include execute permissions, in addition to the read and write permissions seen above.

The permissions in this table, applied to a file, specify execute permissions.

Directory Permissions

Permissions for a directory include search permissions, in addition to the read and write permissions seen above.

The permissions in this table, applied to a directory, specify search permissions.

Special Bits

The fourth octal digit in a mode represents its special bits:

• Its low-order bit (1000) shows whether the sticky bit is set.

• The next bit (2000) shows whether the setuid bit is set.

• The next bit (4000) shows whether the setgid bit is set.

Examples (note value in special-bits digit – fourth-from-left):

filepath = '/tmp/t.tmp'
File.write(filepath, 'foo')
'%06o' % File.stat(filepath).mode # => "100664"  # No special bits set.
File.chmod(0o1644, filepath)
'%06o' % File.stat(filepath).mode # => "101644"  # Sticky bit set.
File.chmod(0o2644, filepath)
'%06o' % File.stat(filepath).mode # => "102644"  # Setgid bit set.
File.chmod(0o4644, filepath)
'%06o' % File.stat(filepath).mode # => "104644"  # Setuid bit set.
File.chmod(0o7644, filepath)
'%06o' % File.stat(filepath).mode # => "107644"  # All special bits set.
File.delete(filepath)             # Clean up.

File Type

The fifth and sixth octal digits in a mode represent the file type:

Define a path for each file type:

pipe_path =              '/tmp/pipe'
character_special_path = '/dev/tty'
dir_path =               '/tmp'
block_special_path =     '/dev/loop0'
file_path =              '/etc/passwd'
link_path =              '/tmp/link'
socket_path =            '/tmp/socket'

For some of the paths, the entries exist already; these we have to create:

File.mkfifo(pipe_path, 0666)
File.symlink(file_path, link_path)
require 'socket'
UNIXServer.new(socket_path)

Show the modes (note the leftmost two digits):

'%06o' % File.stat(pipe_path).mode              # => "010664"
'%06o' % File.stat(character_special_path).mode # => "020666"
'%06o' % File.stat(dir_path).mode               # => "041777"
'%06o' % File.stat(block_special_path).mode     # => "060660"
'%06o' % File.stat(file_path).mode              # => "100644"
'%06o' % File.lstat(link_path).mode             # => "120777"  # lstat: Do not follow link.
'%06o' % File.stat(socket_path).mode            # => "140775"
File.delete(pipe_path, link_path, socket_path)  # Clean up.