CONTENTS

• NAME
• SYNOPSIS
• DESCRIPTION
• EXPORTED SYMBOLS
  • Default exports and export tags
  • Symbols for use with fcntl
  • Symbols for use with flock
  • Symbols for use with sysopen
  • Symbols for use with seek and sysseek
  • Symbols for use with stat and chmod
• SEE ALSO
• APPENDIX A

#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 infcntl.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 tofcntl, 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 (seeExporter 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 toqw(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 withfcntl

#F_ALLOCSP

File storage manipulation.

#F_ALLOCSP64

File storage manipulation.

#F_DUP2FD

Duplicate a file descriptor to the number specified in the third argument tofcntl (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 offcntl.

#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 successfulexec call, the file descriptor will be closed automatically.

#F_GETFL

Return (as a number) the set of file description status flags (O_*) as set byopen andfcntl. To determine the file access mode, perform a bitwise AND with"O_ACCMODE" and see whether the result is equal toO_RDONLY,O_WRONLY, orO_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 of0 meansSIGIO.

#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 thirdfnctl 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 of0 meansSIGIO.

#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 withflock

#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

WithLOCK_MAND: Allow concurrent reads.

#LOCK_RW

WithLOCK_MAND: Allow concurrent reads and writes.

#LOCK_SH

Request a shared lock.

#LOCK_UN

Release a held lock.

#LOCK_WRITE

WithLOCK_MAND: Allow concurrent writes.

#Symbols for use withsysopen

#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 callingfdatasync(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$! toEEXIST (this only makes sense in combination withO_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. UseO_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$! toELOOP.

#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 raiseSIGPIPE for write operations when the read end of the pipe is closed; make the write fail withEPIPE 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 asO_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 ofO_SYNC andO_DSYNC to read operations. In particular, reading from a filehandle opened withO_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 callingfsync(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 itstermios parameters.

#O_WRONLY

Open the file for writing (only).

#FAPPEND

Compatibility symbol. UseO_APPEND instead.

#FASYNC

Compatibility symbol. UseO_ASYNC instead.

#FCREAT

Compatibility symbol. UseO_CREAT instead.

#FDEFER

Compatibility symbol. UseO_DEFER instead.

#FDSYNC

Compatibility symbol. UseO_DSYNC instead.

#FEXCL

Compatibility symbol. UseO_EXCL instead.

#FLARGEFILE

Compatibility symbol. UseO_LARGEFILE instead.

#FNDELAY

Compatibility symbol. UseO_NDELAY instead.

#FNONBLOCK

Compatibility symbol. UseO_NONBLOCK instead.

#FRSYNC

Compatibility symbol. UseO_RSYNC instead.

#FSYNC

Compatibility symbol. UseO_SYNC instead.

#FTRUNC

Compatibility symbol. UseO_TRUNC instead.

#Symbols for use withseek andsysseek

#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 withstat andchmod

#S_ENFMT

Enforce mandatory file locks. (This symbol typically shares its value withS_ISGID.)

#S_IEXEC

Compatibility symbol. UseS_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 toS_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. UseS_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 toS_IFMT($mode) == S_IFBLK.

#S_ISCHR

Convenience function to check for character devices:S_ISCHR($mode) is equivalent toS_IFMT($mode) == S_IFCHR.

#S_ISDIR

Convenience function to check for directories:S_ISDIR($mode) is equivalent toS_IFMT($mode) == S_IFDIR.

#S_ISFIFO

Convenience function to check for fifos:S_ISFIFO($mode) is equivalent toS_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 toS_IFMT($mode) == S_IFLNK.

#S_ISREG

Convenience function to check for regular files:S_ISREG($mode) is equivalent toS_IFMT($mode) == S_IFREG.

#S_ISSOCK

Convenience function to check for sockets:S_ISSOCK($mode) is equivalent toS_IFMT($mode) == S_IFSOCK.

#S_ISTXT

Compatibility symbol. UseS_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 toS_IFMT($mode) == S_IFWHT.

#S_IWGRP

Permissions: Writable by group.

#S_IWOTH

Permissions: Writable by others.

#S_IWRITE

Compatibility symbol. UseS_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 sayuse Fcntl;, the following symbols are exported:

FD_CLOEXECF_ALLOCSPF_ALLOCSP64F_COMPATF_DUP2FDF_DUPFDF_EXLCKF_FREESPF_FREESP64F_FSYNCF_FSYNC64F_GETFDF_GETFLF_GETLKF_GETLK64F_GETOWNF_NODNYF_POSIXF_RDACCF_RDDNYF_RDLCKF_RWACCF_RWDNYF_SETFDF_SETFLF_SETLKF_SETLK64F_SETLKWF_SETLKW64F_SETOWNF_SHAREF_SHLCKF_UNLCKF_UNSHAREF_WRACCF_WRDNYF_WRLCKO_ACCMODEO_ALIASO_APPENDO_ASYNCO_BINARYO_CREATO_DEFERO_DIRECTO_DIRECTORYO_DSYNCO_EXCLO_EXLOCKO_LARGEFILEO_NDELAYO_NOCTTYO_NOFOLLOWO_NOINHERITO_NONBLOCKO_RANDOMO_RAWO_RDONLYO_RDWRO_RSRCO_RSYNCO_SEQUENTIALO_SHLOCKO_SYNCO_TEMPORARYO_TEXTO_TRUNCO_WRONLY

Perldoc Browser is maintained by Dan Book (DBOOK). Please contact him via theGitHub issue tracker oremail regarding any issues with the site itself, search, or rendering of documentation.

The Perl documentation is maintained by the Perl 5 Porters in the development of Perl. Please contact them via thePerl issue tracker, themailing list, orIRC to report any issues with the contents or format of the documentation.