Fcntl(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

💖 NAME 💖

Fcntl(3perl) — various flag constants and helper functions from C's fcntl.h. This is the page from the Perl Programmers Reference Guide, and bestie, it's lowkey a whole toolbox. 🧰✨

✨ SYNOPSIS ✨

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

🦋 DESCRIPTION 🦋

Okay so 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. Periodt. 🌈

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). No cap, read your platform docs. 💅

(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". Go look, bestie, it's right there. ✨

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. It's giving legacy, ngl. 🫠

🔥 Symbols for use with fcntl 🔥

  • F_ALLOCSP — File storage manipulation. very allocate, much storage ✨
  • F_ALLOCSP64 — File storage manipulation. same vibe, 64-bit energy 💫
  • 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). dup and replace, slay. 💅
  • 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. free that space 🦋
  • F_FREESP64 — File storage manipulation. free that space, but 64 🦋
  • F_FSYNC — Synchronize file data to disk. sync it, bestie 🔄
  • F_FSYNC64 — Synchronize file data to disk. sync it, but 64 🔄
  • 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. auto-close on exec, iconic. 👑
  • 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. bitwise detective work, iykyk. 🕵️‍♀️
  • 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. pipe capacity check, cute. 🪈
  • 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. set the flags, bestie. 💅
  • F_SETFL — Set the file description status flags (O_*). Only some flags can be changed this way. only some, don't get it twisted. ⚠️
  • 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. wait for it… ⏳
  • F_SETLKW64 — Acquire a record lock and wait for conflicting locks to be released. wait for it… 64 ⏳
  • 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. may be higher, no promises. 🪈
  • 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). no waiting, we move. 🏃‍♀️
  • 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. mask it up. 🎭
  • 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. end of the line, literally. 📝
  • 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. manifest 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(). deferred till you sync, bestie. 🧠
  • O_DIRECT — Perform direct I/O to/from user-space buffers; avoid caching at the OS level. straight to the source. 🎯
  • 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). exclusive much? 🚫
  • 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). big file energy. 🐘
  • O_NDELAY — Compatibility symbol. Use O_NONBLOCK instead. old and busted, use the new one. 🫠
  • O_NOATIME — Don't update the access time of the file when reading from it. leave that timestamp alone. ⏰
  • 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. no symlink following, periodt. 🚫
  • 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.) no blocking allowed. 🏃‍♀️
  • 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 girlies only 🪟) open the file in text mode.
  • O_TMPFILE — create an unnamed temporary file ✨. The filename argument is where you tell it which directory the unnamed file should be chillin' in.
  • O_TRUNC — if the file already exists, truncate its contents to length 0. say bye to everything in there 😭
  • O_TTY_INIT — if the file you're opening is a terminal that isn't already open in any process, this initializes its termios parameters. glow up for your tty 💅
  • O_WRONLY — open the file for writing (only). no reading allowed, it's giving one-way street 🚦

okay bestie, now we hit the vintage aisle — these next ones are all compatibility symbols, meaning they're the old names kept around for the girlies with ancient code. they all just point at their modern counterpart:

  • 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, they're twins fr.)
  • 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 one 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. iconic duality 💅
  • _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's 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_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). three jobs, one bit, she's booked and busy 👑
  • 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 (the "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 💖

go read these next, they're the extended universe bestie:

🎀 APPENDIX A 🎀

so, by default, if you just say use Fcntl; — no extra vibes, no arguments — the following symbols get exported to you automatically:

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

that's the whole page bestie, you made it to the end 🫶 this came from perl v5.44.0, dated 2026-10-17, and the page is Fcntl(3perl) — go forth and fcntl responsibly, mwah 💋

📦 where this page comes from