package Fcntl;
=head1 NAME
Fcntl - various flag constants and helper functions from C's fcntl.h
=head1 SYNOPSIS
use Fcntl;
use Fcntl qw(:DEFAULT :flock);
use Fcntl qw(F_GETFD F_SETFD FD_CLOEXEC);
=head1 DESCRIPTION
This module provides flags and helper functions for use with L<perlfunc/chmod>
(S_*), L<perlfunc/fcntl> (F_*), L<perlfunc/flock> (LOCK_*), L<perlfunc/seek>
(SEEK_*), L<perlfunc/stat> (S_*), L<perlfunc/sysopen> (O_*), and
L<perlfunc/sysseek> (SEEK_*). They correspond to the C macros defined in
F<fcntl.h>.
Not all symbols are available on all systems. Except where noted otherwise,
the constants and functions provided by this module will throw a runtime
exception if the corresponding C macro is not available. Consult your system
documentation to see the full description of each symbol and whether it is
available on your platform: L<chmod(2)>, L<fcntl(2)>, L<flock(2)>,
L<lseek(2)>, L<open(2)>, L<stat(2)>.
(In particular, some of the F_* symbols are highly non-portable because they
only exist on a single platform or require system-specific C data structures to
be passed as the third argument to C<fcntl>, which can't be portably
constructed in pure Perl.)
=head1 EXPORTED SYMBOLS
=head2 Default exports and export tags
The full list of default exports can be found below in L</APPENDIX A>.
In addition, the following export tags are available (see L<Exporter> for more
information on export tags):
=over
=item C<:DEFAULT>
Equivalent to the list of default export symbols (see L</APPENDIX A>).
=item C<:flock>
Equivalent to all LOCK_* symbols listed below.
=item C<:mode>
Equivalent to all S_* symbols listed below.
=item C<:seek>
Equivalent to all SEEK_* symbols listed below.
=item C<:Fcompat>
Equivalent to C<qw(FAPPEND FASYNC FCREAT FDEFER FDSYNC FEXCL FLARGEFILE FNDELAY
FNONBLOCK FRSYNC FSYNC FTRUNC)>. These only exist for compatibility with old
code (if your platform defines them at all) and should not be used in new code.
=back
=head2 Symbols for use with C<fcntl>
=over
=item C<F_ALLOCSP>
File storage manipulation.
=item C<F_ALLOCSP64>
File storage manipulation.
=item C<F_DUP2FD>
Duplicate a file descriptor to the number specified in the third argument to
C<fcntl> (if it refers to an open file, it is automatically closed first).
=item C<F_DUPFD>
Duplicate a file descriptor to the lowest unused number greater than or equal
to the third argument of C<fcntl>.
=item C<F_FREESP>
File storage manipulation.
=item C<F_FREESP64>
File storage manipulation.
=item C<F_FSYNC>
Synchronize file data to disk.
=item C<F_FSYNC64>
Synchronize file data to disk.
=item C<F_GETFD>
Return (as a number) the set of file descriptor flags, in which the following
bits may be set:
=over
=item C<FD_CLOEXEC>
During a successful C<exec> call, the file descriptor will be closed
automatically.
=back
=item C<F_GETFL>
Return (as a number) the set of file description status flags (O_*) as set by
C<open> and C<fcntl>. To determine the file access mode, perform a bitwise AND
with L</C<O_ACCMODE>> and see whether the result is equal to C<O_RDONLY>,
C<O_WRONLY>, or C<O_RDWR>.
=item C<F_GETLEASE>
Indicate the type of lease associated with the filehandle (if any) by returning
one of the following flags:
=over
=item C<F_RDLCK>
A read lease.
=item C<F_WRLCK>
A write lease.
=item C<F_UNLCK>
No lease.
=back
=item C<F_GETLK>
Test for the existence of record locks on the file.
=item C<F_GETLK64>
Test for the existence of record locks on the file.
=item C<F_GETOWN>
Return the ID of the process (as a positive number) or group (as a negative
number) that is currently receiving signals for events on the file descriptor.
=item C<F_GETPIPE_SZ>
Return the capacity of the pipe associated with the filehandle.
=item C<F_GETSIG>
Return the number of the signal sent when input or output becomes possible on
the filehandle. A return value of C<0> means C<SIGIO>.
=item C<F_NOTIFY>
File and directory change notification with signals.
=over
=item C<DN_ACCESS>
=item C<DN_ATTRIB>
=item C<DN_CREATE>
=item C<DN_DELETE>
=item C<DN_MODIFY>
=item C<DN_MULTISHOT>
=item C<DN_RENAME>
=back
Z<>
=item C<F_SETFD>
Set the file descriptor flags. See L</C<F_GETFD>> for the list of available
flags.
=item C<F_SETFL>
Set the file description status flags (O_*). Only some flags can be changed
this way.
=item C<F_SETLEASE>
Set a file lease as specified by the third C<fnctl> argument, which must be one
of the following:
=over
=item C<F_RDLCK>
Set a read lease.
=item C<F_WRLCK>
Set a write lease.
=item C<F_UNLCK>
Remove a lease.
=back
=item C<F_SETLK>
Acquire a record lock.
=item C<F_SETLK64>
Acquire a record lock.
=item C<F_SETLKW>
Acquire a record lock and wait for conflicting locks to be released.
=item C<F_SETLKW64>
Acquire a record lock and wait for conflicting locks to be released.
=item C<F_SETOWN>
Set the ID of the process (as a positive number) or group (as a negative
number) that will receive signals for events on the file descriptor.
=item C<F_SETPIPE_SZ>
Set the capacity of the pipe associated with the filehandle. Return the actual
capacity reserved for the pipe, which may be higher than requested.
=item C<F_SETSIG>
Set the number of the signal sent when input or output becomes possible on the
filehandle. An argument of C<0> means C<SIGIO>.
=item C<F_SHARE>
Set share reservation.
=item C<F_UNSHARE>
Remove share reservation.
=item C<F_COMPAT>
=item C<F_EXLCK>
=item C<F_NODNY>
=item C<F_POSIX>
=item C<F_RDACC>
=item C<F_RDDNY>
=item C<F_RWACC>
=item C<F_RWDNY>
=item C<F_SHLCK>
=item C<F_WRACC>
=item C<F_WRDNY>
=back
=head2 Symbols for use with C<flock>
=over
=item C<LOCK_EX>
Request an exclusive lock.
=item C<LOCK_MAND>
Request a mandatory lock.
=item C<LOCK_NB>
Make lock request non-blocking (can be combined with other LOCK_* flags using bitwise OR).
=item C<LOCK_READ>
With C<LOCK_MAND>: Allow concurrent reads.
=item C<LOCK_RW>
With C<LOCK_MAND>: Allow concurrent reads and writes.
=item C<LOCK_SH>
Request a shared lock.
=item C<LOCK_UN>
Release a held lock.
=item C<LOCK_WRITE>
With C<LOCK_MAND>: Allow concurrent writes.
=back
=head2 Symbols for use with C<sysopen>
=over
=item C<O_ACCMODE>
Bit mask for extracting the file access mode (read-only, write-only, or
read/write) from the other flags. This is mainly useful in combination with
L</C<F_GETFL>>.
=item C<O_ALIAS>
(Mac OS) Open alias file (instead of the file that the alias refers to).
=item C<O_ALT_IO>
(NetBSD) Use alternative I/O semantics.
=item C<O_APPEND>
Open the file in append mode. Writes always go to the end of the file.
=item C<O_ASYNC>
Enable signal-based I/O. When the file becomes readable or writable, a signal
is sent.
=item C<O_BINARY>
(Windows) Open the file in binary mode.
=item C<O_CREAT>
If the file to be opened does not exist yet, create it.
=item C<O_DEFER>
(AIX) Changes to the file are kept in memory and not written to disk until the
program performs an explicit L<< C<< $fh->sync() >>|IO::Handle/$io->sync >>.
=item C<O_DIRECT>
Perform direct I/O to/from user-space buffers; avoid caching at the OS level.
=item C<O_DIRECTORY>
Fail if the filename to be opened does not refer to a directory.
=item C<O_DSYNC>
Synchronize file data immediately, like calling L<fdatasync(2)> after each
write.
=item C<O_EVTONLY>
(Mac OS) Open the file for event notifications, not reading or writing.
=item C<O_EXCL>
If the file already exists, fail and set C<$!> to L<C<EEXIST>|Errno> (this only
makes sense in combination with C<O_CREAT>).
=item C<O_EXLOCK>
When the file is opened, atomically obtain an exclusive lock.
=item C<O_IGNORE_CTTY>
(Hurd) If the file to be opened is the controlling terminal for this process,
don't recognize it as such. Operations on this filehandle won't trigger job
control signals.
=item C<O_LARGEFILE>
On 32-bit platforms, allow opening files whose size exceeds 2 GiB
(2,147,483,647 bytes).
=item C<O_NDELAY>
Compatibility symbol. Use C<O_NONBLOCK> instead.
=item C<O_NOATIME>
Don't update the access time of the file when reading from it.
=item C<O_NOCTTY>
If the process does not have a controlling terminal and the file to be opened
is a terminal device, don't make it the controlling terminal of the process.
=item C<O_NOFOLLOW>
If the final component of the filename is a symbolic link, fail and set C<$!>
to L<C<ELOOP>|Errno>.
=item C<O_NOINHERIT>
(Windows) Don't let child processes inherit the opened file descriptor.
=item C<O_NOLINK>
(Hurd) If the file to be opened is a symbolic link, don't follow it; open the
link itself.
=item C<O_NONBLOCK>
Open the file in non-blocking mode. Neither the open itself nor any read/write
operations on the filehandle will block. (This is mainly useful for pipes and
sockets. It has no effect on regular files.)
=item C<O_NOSIGPIPE>
If the file to be opened is a pipe, then don't raise C<SIGPIPE> for write
operations when the read end of the pipe is closed; make the write fail with
C<EPIPE> instead.
=item C<O_NOTRANS>
(Hurd) If the file to be opened is specially translated, don't invoke the
translator; open the bare file itself.
=item C<O_RANDOM>
(Windows) Indicate that the program intends to access the file contents
randomly (without a predictable pattern). This is an optimization hint for the
file cache (but may cause excessive memory use on large files).
=item C<O_RAW>
(Windows) Same as C<O_BINARY>.
=item C<O_RDONLY>
Open the file for reading (only).
=item C<O_RDWR>
Open the file for reading and writing.
=item C<O_RSRC>
(Mac OS) Open the resource fork of the file.
=item C<O_RSYNC>
Extend the effects of C<O_SYNC> and C<O_DSYNC> to read operations. In
particular, reading from a filehandle opened with C<O_SYNC | O_RSYNC> will wait
until the access time of the file has been modified on disk.
=item C<O_SEQUENTIAL>
(Windows) Indicate that the program intends to access the file contents
sequentially. This is an optimization hint for the file cache.
=item C<O_SHLOCK>
When the file is opened, atomically obtain a shared lock.
=item C<O_SYMLINK>
If the file to be opened is a symbolic link, don't follow it; open the link
itself.
=item C<O_SYNC>
Synchronize file data and metadata immediately, like calling L<fsync(2)> after
each write.
=item C<O_TEMPORARY>
(Windows) Delete the file when its last open file descriptor is closed.
=item C<O_TEXT>
(Windows) Open the file in text mode.
=item C<O_TMPFILE>
Create an unnamed temporary file. The filename argument specifies the directory
the unnamed file should be placed in.
=item C<O_TRUNC>
If the file already exists, truncate its contents to length 0.
=item C<O_TTY_INIT>
If the file to be opened is a terminal that is not already open in any process,
initialize its L<termios|POSIX/C<POSIX::Termios>> parameters.
=item C<O_WRONLY>
Open the file for writing (only).
=item C<FAPPEND>
Compatibility symbol. Use C<O_APPEND> instead.
=item C<FASYNC>
Compatibility symbol. Use C<O_ASYNC> instead.
=item C<FCREAT>
Compatibility symbol. Use C<O_CREAT> instead.
=item C<FDEFER>
Compatibility symbol. Use C<O_DEFER> instead.
=item C<FDSYNC>
Compatibility symbol. Use C<O_DSYNC> instead.
=item C<FEXCL>
Compatibility symbol. Use C<O_EXCL> instead.
=item C<FLARGEFILE>
Compatibility symbol. Use C<O_LARGEFILE> instead.
=item C<FNDELAY>
Compatibility symbol. Use C<O_NDELAY> instead.
=item C<FNONBLOCK>
Compatibility symbol. Use C<O_NONBLOCK> instead.
=item C<FRSYNC>
Compatibility symbol. Use C<O_RSYNC> instead.
=item C<FSYNC>
Compatibility symbol. Use C<O_SYNC> instead.
=item C<FTRUNC>
Compatibility symbol. Use C<O_TRUNC> instead.
=back
=head2 Symbols for use with C<seek> and C<sysseek>
=over
=item C<SEEK_CUR>
File offsets are relative to the current position in the file.
=item C<SEEK_END>
File offsets are relative to the end of the file (i.e. mostly negative).
=item C<SEEK_SET>
File offsets are absolute (i.e. relative to the beginning of the file).
=back
=head2 Symbols for use with C<stat> and C<chmod>
=over
=item C<S_ENFMT>
Enforce mandatory file locks. (This symbol typically shares its value with
C<S_ISGID>.)
=item C<S_IEXEC>
Compatibility symbol. Use C<S_IXUSR> instead.
=item C<S_IFBLK>
File type: Block device.
=item C<S_IFCHR>
File type: Character device.
=item C<S_IFDIR>
File type: Directory.
=item C<S_IFIFO>
File type: Fifo/pipe.
=item C<S_IFLNK>
File type: Symbolic link.
=item C<S_IFMT>
Bit mask for extracting the file type bits. This symbol can also be used as a
function: C<S_IFMT($mode)> acts like C<$mode & S_IFMT>. The result will be
equal to one of the other S_IF* constants.
=item C<_S_IFMT>
Bit mask for extracting the file type bits. This symbol is an actual constant
and cannot be used as a function; otherwise it is identical to C<S_IFMT>.
=item C<S_IFREG>
File type: Regular file.
=item C<S_IFSOCK>
File type: Socket.
=item C<S_IFWHT>
File type: Whiteout file (used to mark the absence/deletion of a file in overlays).
=item C<S_IMODE>
Function for extracting the permission bits from a file mode.
=item C<S_IREAD>
Compatibility symbol. Use C<S_IRUSR> instead.
=item C<S_IRGRP>
Permissions: Readable by group.
=item C<S_IROTH>
Permissions: Readable by others.
=item C<S_IRUSR>
Permissions: Readable by owner.
=item C<S_IRWXG>
Bit mask for extracting group permissions.
=item C<S_IRWXO>
Bit mask for extracting other permissions.
=item C<S_IRWXU>
Bit mask for extracting owner ("user") permissions.
=item C<S_ISBLK>
Convenience function to check for block devices: C<S_ISBLK($mode)> is
equivalent to C<S_IFMT($mode) == S_IFBLK>.
=item C<S_ISCHR>
Convenience function to check for character devices: C<S_ISCHR($mode)> is
equivalent to C<S_IFMT($mode) == S_IFCHR>.
=item C<S_ISDIR>
Convenience function to check for directories: C<S_ISDIR($mode)> is
equivalent to C<S_IFMT($mode) == S_IFDIR>.
=item C<S_ISENFMT>
Broken function; do not use. (C<S_ISENFMT($mode)> should always return false,
anyway.)
=item C<S_ISFIFO>
Convenience function to check for fifos: C<S_ISFIFO($mode)> is
equivalent to C<S_IFMT($mode) == S_IFIFO>.
=item C<S_ISGID>
Permissions: Set effective group ID from file (when running executables);
mandatory locking (on non-group-executable files); new files inherit their
group from the directory (on directories).
=item C<S_ISLNK>
Convenience function to check for symbolic links: C<S_ISLNK($mode)> is
equivalent to C<S_IFMT($mode) == S_IFLNK>.
=item C<S_ISREG>
Convenience function to check for regular files: C<S_ISREG($mode)> is
equivalent to C<S_IFMT($mode) == S_IFREG>.
=item C<S_ISSOCK>
Convenience function to check for sockets: C<S_ISSOCK($mode)> is
equivalent to C<S_IFMT($mode) == S_IFSOCK>.
=item C<S_ISTXT>
Compatibility symbol. Use C<S_ISVTX> instead.
=item C<S_ISUID>
Permissions: Set effective user ID from file (when running executables).
=item C<S_ISVTX>
Permissions: Files in this directory can only be deleted/renamed by their owner
(or the directory's owner), even if other users have write permissions to the
directory ("sticky bit").
=item C<S_ISWHT>
Convenience function to check for whiteout files: C<S_ISWHT($mode)> is
equivalent to C<S_IFMT($mode) == S_IFWHT>.
=item C<S_IWGRP>
Permissions: Writable by group.
=item C<S_IWOTH>
Permissions: Writable by others.
=item C<S_IWRITE>
Compatibility symbol. Use C<S_IWUSR> instead.
=item C<S_IWUSR>
Permissions: Writable by owner.
=item C<S_IXGRP>
Permissions: Executable/searchable by group.
=item C<S_IXOTH>
Permissions: Executable/searchable by others.
=item C<S_IXUSR>
Permissions: Executable/searchable by owner.
=back
=head1 SEE ALSO
L<perlfunc/chmod>, L<chmod(2)>,
L<perlfunc/fcntl>, L<fcntl(2)>,
L<perlfunc/flock>, L<flock(2)>,
L<perlfunc/seek>, L<fseek(3)>,
L<perlfunc/stat>, L<stat(2)>,
L<perlfunc/sysopen>, L<open(2)>,
L<perlfunc/sysseek>, L<lseek(2)>
=head1 APPENDIX A
By default, if you say C<use Fcntl;>, the following symbols are exported:
FD_CLOEXEC
F_ALLOCSP
F_ALLOCSP64
F_COMPAT
F_DUP2FD
F_DUPFD
F_EXLCK
F_FREESP
F_FREESP64
F_FSYNC
F_FSYNC64
F_GETFD
F_GETFL
F_GETLK
F_GETLK64
F_GETOWN
F_NODNY
F_POSIX
F_RDACC
F_RDDNY
F_RDLCK
F_RWACC
F_RWDNY
F_SETFD
F_SETFL
F_SETLK
F_SETLK64
F_SETLKW
F_SETLKW64
F_SETOWN
F_SHARE
F_SHLCK
F_UNLCK
F_UNSHARE
F_WRACC
F_WRDNY
F_WRLCK
O_ACCMODE
O_ALIAS
O_APPEND
O_ASYNC
O_BINARY
O_CREAT
O_DEFER
O_DIRECT
O_DIRECTORY
O_DSYNC
O_EXCL
O_EXLOCK
O_LARGEFILE
O_NDELAY
O_NOCTTY
O_NOFOLLOW
O_NOINHERIT
O_NONBLOCK
O_RANDOM
O_RAW
O_RDONLY
O_RDWR
O_RSRC
O_RSYNC
O_SEQUENTIAL
O_SHLOCK
O_SYNC
O_TEMPORARY
O_TEXT
O_TRUNC
O_WRONLY
=cut
use strict;
use Exporter 'import';
require XSLoader;
our $VERSION = '1.18';
XSLoader::load();
# Named groups of exports
our %EXPORT_TAGS = (
'flock' => [qw(LOCK_SH LOCK_EX LOCK_NB LOCK_UN)],
'Fcompat' => [qw(FAPPEND FASYNC FCREAT FDEFER FDSYNC FEXCL FLARGEFILE
FNDELAY FNONBLOCK FRSYNC FSYNC FTRUNC)],
'seek' => [qw(SEEK_SET SEEK_CUR SEEK_END)],
'mode' => [qw(S_ISUID S_ISGID S_ISVTX S_ISTXT
_S_IFMT S_IFREG S_IFDIR S_IFLNK
S_IFSOCK S_IFBLK S_IFCHR S_IFIFO S_IFWHT S_ENFMT
S_IRUSR S_IWUSR S_IXUSR S_IRWXU
S_IRGRP S_IWGRP S_IXGRP S_IRWXG
S_IROTH S_IWOTH S_IXOTH S_IRWXO
S_IREAD S_IWRITE S_IEXEC
S_ISREG S_ISDIR S_ISLNK S_ISSOCK
S_ISBLK S_ISCHR S_ISFIFO
S_ISWHT S_ISENFMT
S_IFMT S_IMODE
)],
);
# Items to export into callers namespace by default
# (move infrequently used names to @EXPORT_OK below)
our @EXPORT =
qw(
FD_CLOEXEC
F_ALLOCSP
F_ALLOCSP64
F_COMPAT
F_DUP2FD
F_DUPFD
F_EXLCK
F_FREESP
F_FREESP64
F_FSYNC
F_FSYNC64
F_GETFD
F_GETFL
F_GETLK
F_GETLK64
F_GETOWN
F_NODNY
F_POSIX
F_RDACC
F_RDDNY
F_RDLCK
F_RWACC
F_RWDNY
F_SETFD
F_SETFL
F_SETLK
F_SETLK64
F_SETLKW
F_SETLKW64
F_SETOWN
F_SHARE
F_SHLCK
F_UNLCK
F_UNSHARE
F_WRACC
F_WRDNY
F_WRLCK
O_ACCMODE
O_ALIAS
O_APPEND
O_ASYNC
O_BINARY
O_CREAT
O_DEFER
O_DIRECT
O_DIRECTORY
O_DSYNC
O_EXCL
O_EXLOCK
O_LARGEFILE
O_NDELAY
O_NOCTTY
O_NOFOLLOW
O_NOINHERIT
O_NONBLOCK
O_RANDOM
O_RAW
O_RDONLY
O_RDWR
O_RSRC
O_RSYNC
O_SEQUENTIAL
O_SHLOCK
O_SYNC
O_TEMPORARY
O_TEXT
O_TRUNC
O_WRONLY
);
# Other items we are prepared to export if requested
our @EXPORT_OK = (qw(
DN_ACCESS
DN_ATTRIB
DN_CREATE
DN_DELETE
DN_MODIFY
DN_MULTISHOT
DN_RENAME
F_ADD_SEALS
F_GETLEASE
F_GETPIPE_SZ
F_GET_SEALS
F_GETSIG
F_NOTIFY
F_SEAL_FUTURE_WRITE
F_SEAL_GROW
F_SEAL_SEAL
F_SEAL_SHRINK
F_SEAL_WRITE
F_SETLEASE
F_SETPIPE_SZ
F_SETSIG
LOCK_MAND
LOCK_READ
LOCK_RW
LOCK_WRITE
O_ALT_IO
O_EVTONLY
O_IGNORE_CTTY
O_NOATIME
O_NOLINK
O_NOSIGPIPE
O_NOTRANS
O_SYMLINK
O_TMPFILE
O_TTY_INIT
), map {@{$_}} values %EXPORT_TAGS);
1;