—

              
package Fcntl;
HideShow 853 lines of Pod
=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;