Fcntl(3p) | Perl Programmers Reference Guide | Fcntl(3p)

# NAME

Fcntl - various flag constants and helper functions from C's fcntl.h

# SYNOPSIS

        use Fcntl;
        use Fcntl qw(:DEFAULT :flock);
        use Fcntl qw(F_GETFD F_SETFD FD_CLOEXEC);

# DESCRIPTION

This module provides flags and helper functions for use with "chmod" in perlfunc (S_*), "fcntl" in perlfunc (F_*), "flock" in perlfunc (LOCK_*), "seek" in perlfunc (SEEK_*), "stat" in perlfunc (S_*), "sysopen" in perlfunc (O_*), and "sysseek" in perlfunc (SEEK_*). They correspond to the C macros defined in 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: chmod(2), fcntl(2), flock(2), lseek(2), open(2), 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 "fcntl", which can't be portably constructed in pure Perl.)

# EXPORTED SYMBOLS

## Default exports and export tags

The full list of default exports can be found below in "APPENDIX A".

In addition, the following export tags are available (see Exporter for more information on export tags):

":DEFAULT"
  Equivalent to the list of default export symbols (see "APPENDIX A").
":flock"
  Equivalent to all LOCK_* symbols listed below.
":mode"
  Equivalent to all S_* symbols listed below.
":seek"
  Equivalent to all SEEK_* symbols listed below.
":Fcompat"
  Equivalent to "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.

## Symbols for use with "fcntl"

"F_ALLOCSP"
  File storage manipulation.
"F_ALLOCSP64"
  File storage manipulation.
"F_DUP2FD"
  Duplicate a file descriptor to the number specified in the third argument to "fcntl" (if it refers to an open file, it is automatically closed first).
"F_DUPFD"
  Duplicate a file descriptor to the lowest unused number greater than or equal to the third argument of "fcntl".
"F_FREESP"
  File storage manipulation.
"F_FREESP64"
  File storage manipulation.
"F_FSYNC"
  Synchronize file data to disk.
"F_FSYNC64"
  Synchronize file data to disk.
"F_GETFD"
  Return (as a number) the set of file descriptor flags, in which the following bits may be set:

"FD_CLOEXEC"
  During a successful "exec" call, the file descriptor will be closed automatically.

"F_GETFL"
  Return (as a number) the set of file description status flags (O_*) as set by "open" and "fcntl". To determine the file access mode, perform a bitwise AND with ""O_ACCMODE"" and see whether the result is equal to "O_RDONLY", "O_WRONLY", or "O_RDWR".
"F_GETLEASE"
  Indicate the type of lease associated with the filehandle (if any) by returning one of the following flags:

"F_RDLCK"
  A read lease.
"F_WRLCK"
  A write lease.
"F_UNLCK"
  No lease.

"F_GETLK"
  Test for the existence of record locks on the file.
"F_GETLK64"
  Test for the existence of record locks on the file.
"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.
"F_GETPIPE_SZ"
  Return the capacity of the pipe associated with the filehandle.
"F_GETSIG"
  Return the number of the signal sent when input or output becomes possible on the filehandle. A return value of 0 means "SIGIO".
"F_NOTIFY"
  File and directory change notification with signals.

"DN_ACCESS"
"DN_ATTRIB"
"DN_CREATE"
"DN_DELETE"
"DN_MODIFY"
"DN_MULTISHOT"
"DN_RENAME"

"F_SETFD"
  Set the file descriptor flags. See ""F_GETFD"" for the list of available flags.
"F_SETFL"
  Set the file description status flags (O_*). Only some flags can be changed this way.
"F_SETLEASE"
  Set a file lease as specified by the third "fnctl" argument, which must be one of the following:

"F_RDLCK"
  Set a read lease.
"F_WRLCK"
  Set a write lease.
"F_UNLCK"
  Remove a lease.

"F_SETLK"
  Acquire a record lock.
"F_SETLK64"
  Acquire a record lock.
"F_SETLKW"
  Acquire a record lock and wait for conflicting locks to be released.
"F_SETLKW64"
  Acquire a record lock and wait for conflicting locks to be released.
"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.
"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.
"F_SETSIG"
  Set the number of the signal sent when input or output becomes possible on the filehandle. An argument of 0 means "SIGIO".
"F_SHARE"
  Set share reservation.
"F_UNSHARE"
  Remove share reservation.
"F_COMPAT"
"F_EXLCK"
"F_NODNY"
"F_POSIX"
"F_RDACC"
"F_RDDNY"
"F_RWACC"
"F_RWDNY"
"F_SHLCK"
"F_WRACC"
"F_WRDNY"

## Symbols for use with "flock"

"LOCK_EX"
  Request an exclusive lock.
"LOCK_MAND"
  Request a mandatory lock.
"LOCK_NB"
  Make lock request non-blocking (can be combined with other LOCK_* flags using bitwise OR).
"LOCK_READ"
  With "LOCK_MAND": Allow concurrent reads.
"LOCK_RW"
  With "LOCK_MAND": Allow concurrent reads and writes.
"LOCK_SH"
  Request a shared lock.
"LOCK_UN"
  Release a held lock.
"LOCK_WRITE"
  With "LOCK_MAND": Allow concurrent writes.

## Symbols for use with "sysopen"

"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 ""F_GETFL"".
"O_ALIAS"
  (Mac OS) Open alias file (instead of the file that the alias refers to).
"O_ALT_IO"
  (NetBSD) Use alternative I/O semantics.
"O_APPEND"
  Open the file in append mode. Writes always go to the end of the file.
"O_ASYNC"
  Enable signal-based I/O. When the file becomes readable or writable, a signal is sent.
"O_BINARY"
  (Windows) Open the file in binary mode.
"O_CREAT"
  If the file to be opened does not exist yet, create it.
"O_DEFER"
  (AIX) Changes to the file are kept in memory and not written to disk until the program performs an explicit "$fh->sync()".
"O_DIRECT"
  Perform direct I/O to/from user-space buffers; avoid caching at the OS level.
"O_DIRECTORY"
  Fail if the filename to be opened does not refer to a directory.
"O_DSYNC"
  Synchronize file data immediately, like calling fdatasync(2) after each write.
"O_EVTONLY"
  (Mac OS) Open the file for event notifications, not reading or writing.
"O_EXCL"
  If the file already exists, fail and set $! to "EEXIST" (this only makes sense in combination with "O_CREAT").
"O_EXLOCK"
  When the file is opened, atomically obtain an exclusive lock.
"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.
"O_LARGEFILE"
  On 32-bit platforms, allow opening files whose size exceeds 2 GiB (2,147,483,647 bytes).
"O_NDELAY"
  Compatibility symbol. Use "O_NONBLOCK" instead.
"O_NOATIME"
  Don't update the access time of the file when reading from it.
"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.
"O_NOFOLLOW"
  If the final component of the filename is a symbolic link, fail and set $! to "ELOOP".
"O_NOINHERIT"
  (Windows) Don't let child processes inherit the opened file descriptor.
"O_NOLINK"
  (Hurd) If the file to be opened is a symbolic link, don't follow it; open the link itself.
"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.)
"O_NOSIGPIPE"
  If the file to be opened is a pipe, then don't raise "SIGPIPE" for write operations when the read end of the pipe is closed; make the write fail with "EPIPE" instead.
"O_NOTRANS"
  (Hurd) If the file to be opened is specially translated, don't invoke the translator; open the bare file itself.
"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).
"O_RAW"
  (Windows) Same as "O_BINARY".
"O_RDONLY"
  Open the file for reading (only).
"O_RDWR"
  Open the file for reading and writing.
"O_RSRC"
  (Mac OS) Open the resource fork of the file.
"O_RSYNC"
  Extend the effects of "O_SYNC" and "O_DSYNC" to read operations. In particular, reading from a filehandle opened with "O_SYNC | O_RSYNC" will wait until the access time of the file has been modified on disk.
"O_SEQUENTIAL"
  (Windows) Indicate that the program intends to access the file contents sequentially. This is an optimization hint for the file cache.
"O_SHLOCK"
  When the file is opened, atomically obtain a shared lock.
"O_SYMLINK"
  If the file to be opened is a symbolic link, don't follow it; open the link itself.
"O_SYNC"
  Synchronize file data and metadata immediately, like calling fsync(2) after each write.
"O_TEMPORARY"
  (Windows) Delete the file when its last open file descriptor is closed.
"O_TEXT"
  (Windows) Open the file in text mode.
"O_TMPFILE"
  Create an unnamed temporary file. The filename argument specifies the directory the unnamed file should be placed in.
"O_TRUNC"
  If the file already exists, truncate its contents to length 0.
"O_TTY_INIT"
  If the file to be opened is a terminal that is not already open in any process, initialize its termios parameters.
"O_WRONLY"
  Open the file for writing (only).
"FAPPEND"
  Compatibility symbol. Use "O_APPEND" instead.
"FASYNC"
  Compatibility symbol. Use "O_ASYNC" instead.
"FCREAT"
  Compatibility symbol. Use "O_CREAT" instead.
"FDEFER"
  Compatibility symbol. Use "O_DEFER" instead.
"FDSYNC"
  Compatibility symbol. Use "O_DSYNC" instead.
"FEXCL"
  Compatibility symbol. Use "O_EXCL" instead.
"FLARGEFILE"
  Compatibility symbol. Use "O_LARGEFILE" instead.
"FNDELAY"
  Compatibility symbol. Use "O_NDELAY" instead.
"FNONBLOCK"
  Compatibility symbol. Use "O_NONBLOCK" instead.
"FRSYNC"
  Compatibility symbol. Use "O_RSYNC" instead.
"FSYNC"
  Compatibility symbol. Use "O_SYNC" instead.
"FTRUNC"
  Compatibility symbol. Use "O_TRUNC" instead.

## Symbols for use with "seek" and "sysseek"

"SEEK_CUR"
  File offsets are relative to the current position in the file.
"SEEK_END"
  File offsets are relative to the end of the file (i.e. mostly negative).
"SEEK_SET"
  File offsets are absolute (i.e. relative to the beginning of the file).

## Symbols for use with "stat" and "chmod"

"S_ENFMT"
  Enforce mandatory file locks. (This symbol typically shares its value with "S_ISGID".)
"S_IEXEC"
  Compatibility symbol. Use "S_IXUSR" instead.
"S_IFBLK"
  File type: Block device.
"S_IFCHR"
  File type: Character device.
"S_IFDIR"
  File type: Directory.
"S_IFIFO"
  File type: Fifo/pipe.
"S_IFLNK"
  File type: Symbolic link.
"S_IFMT"
  Bit mask for extracting the file type bits. This symbol can also be used as a function: S_IFMT($mode) acts like "$mode & S_IFMT". The result will be equal to one of the other S_IF* constants.
"_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 "S_IFMT".
"S_IFREG"
  File type: Regular file.
"S_IFSOCK"
  File type: Socket.
"S_IFWHT"
  File type: Whiteout file (used to mark the absence/deletion of a file in overlays).
"S_IMODE"
  Function for extracting the permission bits from a file mode.
"S_IREAD"
  Compatibility symbol. Use "S_IRUSR" instead.
"S_IRGRP"
  Permissions: Readable by group.
"S_IROTH"
  Permissions: Readable by others.
"S_IRUSR"
  Permissions: Readable by owner.
"S_IRWXG"
  Bit mask for extracting group permissions.
"S_IRWXO"
  Bit mask for extracting other permissions.
"S_IRWXU"
  Bit mask for extracting owner ("user") permissions.
"S_ISBLK"
  Convenience function to check for block devices: S_ISBLK($mode) is equivalent to "S_IFMT($mode) == S_IFBLK".
"S_ISCHR"
  Convenience function to check for character devices: S_ISCHR($mode) is equivalent to "S_IFMT($mode) == S_IFCHR".
"S_ISDIR"
  Convenience function to check for directories: S_ISDIR($mode) is equivalent to "S_IFMT($mode) == S_IFDIR".
"S_ISENFMT"
  Broken function; do not use. (S_ISENFMT($mode) should always return false, anyway.)
"S_ISFIFO"
  Convenience function to check for fifos: S_ISFIFO($mode) is equivalent to "S_IFMT($mode) == S_IFIFO".
"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).
"S_ISLNK"
  Convenience function to check for symbolic links: S_ISLNK($mode) is equivalent to "S_IFMT($mode) == S_IFLNK".
"S_ISREG"
  Convenience function to check for regular files: S_ISREG($mode) is equivalent to "S_IFMT($mode) == S_IFREG".
"S_ISSOCK"
  Convenience function to check for sockets: S_ISSOCK($mode) is equivalent to "S_IFMT($mode) == S_IFSOCK".
"S_ISTXT"
  Compatibility symbol. Use "S_ISVTX" instead.
"S_ISUID"
  Permissions: Set effective user ID from file (when running executables).
"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").
"S_ISWHT"
  Convenience function to check for whiteout files: S_ISWHT($mode) is equivalent to "S_IFMT($mode) == S_IFWHT".
"S_IWGRP"
  Permissions: Writable by group.
"S_IWOTH"
  Permissions: Writable by others.
"S_IWRITE"
  Compatibility symbol. Use "S_IWUSR" instead.
"S_IWUSR"
  Permissions: Writable by owner.
"S_IXGRP"
  Permissions: Executable/searchable by group.
"S_IXOTH"
  Permissions: Executable/searchable by others.
"S_IXUSR"
  Permissions: Executable/searchable by owner.

# SEE ALSO

"chmod" in perlfunc, chmod(2), "fcntl" in perlfunc, fcntl(2), "flock" in perlfunc, flock(2), "seek" in perlfunc, fseek(3), "stat" in perlfunc, stat(2), "sysopen" in perlfunc, open(2), "sysseek" in perlfunc, lseek(2)

# APPENDIX A

By default, if you say "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

2025-01-28 | perl v5.40.1