Skip to content

Commit

Permalink
perlfunc/stat: fix description of S_ENFMT and S_IFMT
Browse files Browse the repository at this point in the history
S_ENFMT properly belongs to the group of permission bits (like
setuid/setgid), not file types. On systems that have it (like AIX), it
can be set/cleared with chmod(). (In fact, it usually shares its value
with S_ISGID because enforced locking is signaled by the combination of
a non-executable file with the setgid bit set.)

S_IFMT($mode) directly gives you one of the file types (S_IFREG,
S_IFDIR, etc). You don't need to bit-and it further (especially not with
the S_IS* functions), contrary to what the comment claims. (The
confusion likely stems from the C side of things, where you'd do `mode &
S_IFMT` to extract the file type from the mode bits, leading to code
like `(mode & S_IFMT) == S_IFDIR`. But even then you could write
`S_ISDIR(mode)` without any bit mask trickery.)

Most of the symbols in the "S_IF* constants" section don't start with
"S_IF", so change to "S_I* constants" everywhere.

Most of the symbols in the "S_IF* functions" section don't start with
"S_IF" (with the sole exception of S_IFMT, which is only a function in
Perl; the C macro is a constant).
(Historical note: This section label used to make more sense because it
documented S_IFMODE and S_IFMT functions, but the former was just a typo
for S_IMODE.)
  • Loading branch information
mauke committed May 17, 2024
1 parent 2fc32c2 commit 643108f
Showing 1 changed file with 12 additions and 11 deletions.
23 changes: 12 additions & 11 deletions pod/perlfunc.pod
Original file line number Diff line number Diff line change
Expand Up @@ -8956,8 +8956,8 @@ The L<File::stat> module provides a convenient, by-name access mechanism:
$filename, $sb->size, $sb->mode & 07777,
scalar localtime $sb->mtime;

You can import symbolic mode constants (C<S_IF*>) and functions
(C<S_IS*>) from the L<Fcntl> module:
You can import symbolic mode constants and functions
(C<S_I*>) from the L<Fcntl> module:

use Fcntl ':mode';

Expand All @@ -8973,38 +8973,39 @@ You can import symbolic mode constants (C<S_IF*>) and functions
my $is_directory = S_ISDIR($mode);

You could write the last two using the C<-u> and C<-d> operators.
Commonly available C<S_IF*> constants are:
Commonly available C<S_I*> constants are:

# Permissions: read, write, execute, for user, group, others.

S_IRWXU S_IRUSR S_IWUSR S_IXUSR
S_IRWXG S_IRGRP S_IWGRP S_IXGRP
S_IRWXO S_IROTH S_IWOTH S_IXOTH

# Setuid/Setgid/Stickiness/SaveText.
# Setuid/Setgid/Stickiness/SaveText/EnforcedLocks.
# Note that the exact meaning of these is system-dependent.

S_ISUID S_ISGID S_ISVTX S_ISTXT
S_ISUID S_ISGID S_ISVTX S_ISTXT S_ENFMT

# File types. Not all are necessarily available on
# your system.

S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR
S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
S_IFIFO S_IFSOCK S_IFWHT

# The following are compatibility aliases for S_IRUSR,
# S_IWUSR, and S_IXUSR.

S_IREAD S_IWRITE S_IEXEC

and the C<S_IF*> functions are
and the C<S_I*> functions are

S_IMODE($mode) the part of $mode containing the permission
bits and the setuid/setgid/sticky bits

S_IFMT($mode) the part of $mode containing the file type
which can be bit-anded with (for example)
S_IFREG or with the following functions
S_IFMT($mode) the part of $mode containing the file type,
which will match one of the S_IF* constants
(e.g. S_IFMT($mode) == S_IFDIR for directories),
but see the following helper functions

# The operators -f, -d, -l, -b, -c, -p, and -S.

Expand All @@ -9018,7 +9019,7 @@ and the C<S_IF*> functions are
S_ISENFMT($mode) S_ISWHT($mode)

See your native L<chmod(2)> and L<stat(2)> documentation for more details
about the C<S_*> constants. To get status info for a symbolic link
about the C<S_I*> constants. To get status info for a symbolic link
instead of the target file behind the link, use the
L<C<lstat>|/lstat FILEHANDLE> function.

Expand Down

0 comments on commit 643108f

Please sign in to comment.