NAME

POSIX::1003::Fcntl - POSIX function fcntl

SYNOPSIS

use POSIX::1003::Fcntl;

DESCRIPTION

One function, which hides many tricks with file-descriptors. This module tries to provide functions which separates the various uses.

FUNCTIONS

Standard POSIX

fcntl($fd, $function, SCALAR)

See perlfunc fcntl. This raw call to fcntl() is only in some cases simple, but often isn't.

flockfd($fd, $flags)

Not standard POSIX, but available on many POSIX platforms. Often implemented as fcntl(), which is more complex to use. On other platforms implemented as separate OS feature.

Perl core provides a flock which may hide plaform differences. This flockfd is the pure version. Try to use setfd_lock(), which is more portable and flexible.

example:

use POSIX::1003::Fcntl ':flock';
if(flockfd $fd, LOCK_EX|LOCK_NB) ...
flockfd $fd, LOCK_UN;

lockf($fd, $flag, $length)

Not standard POSIX, but available on many POSIX platforms. Often implemented via fcntl(), which is more complex to use.

example:

use POSIX::1003::Fcntl ':lockfd';
if(lockf $fd, F_LOCK) ...
lockf $fd, F_ULOCK;

Additional

fcntl_dup($fd|$fh, %options)

Commands F_DUPFD and F_DUPFD_CLOEXEC: dupplicate a file-descriptor to the lowest free fd number.

-Option       --Default
 close_on_exec  <false>

close_on_exec => BOOLEAN

example:

my $dup_fd = fcntl_dup \*STDOUT;
my $dup_fd = fcntl_dup 2, close_on_exec => 1;

getfd_control($fd|$fh)

Control the file descriptor flags, command F_GETFD.

getfd_flags($fd|$fh)

Get the file status flags and access modes, command F_GETFL.

example:

my $flags = getfd_flags(fd);
if ((flags & O_ACCMODE) == O_RDWR)

getfd_islocked($fd|$fh, %options)

Command F_GETLCK. Returns the first lock which would prevent getting the lock. The %options are the same as for setfd_lock().

example:

if(my $lock = getfd_islocked \*IN) ...

getfd_lease($fd|$fh)

Command F_GETLEASE.

example:

my $lease = getfd_lease(\*STDIN) or die $!;
if($lease != F_RDLCK) ...

getfd_owner($fd|$fh, %options)

Commands F_GETOWN and F_GETOWN_EX.

example:

my ($type, $pid) = getfd_owner($fd);
defined $type or die $!;
if($type==F_OWNER_PGRP) ...

my $pid = getfd_owner($fd) or die $!;

getfd_pipe_size($fd|$fh)

Command F_GETPIPE_SZ.

example:

my $size = getfd_pipe_size($pipe) or die $!;

getfd_signal($fd|$fh)

Command F_GETSIG.

example:

my $signal = getfd_signal(\*STDOUT) or die $!;

setfd_control($fd|$fh, $flags)

Change the file descriptor flags, command F_SETFD.

setfd_flags($fd|$fh, $flags)

Change the file status flags and access modes, command F_SETFL.

setfd_lease($fd|$fh, $flags)

Command F_SETLEASE.

example:

setfd_lease(\*STDOUT, F_WRLCK) or die $!;

setfd_lock($fd|$fh, %options)

Commands F_SETLKP and F_SETLKWP. Request a lock for (a section of) a file.

-Option --Default
 len      <until end of file>
 private  <false>
 start    0
 type     F_RDLCK
 wait     <false>
 whence   SEEK_SET

len => BLOCK_LENGTH

private => BOOLEAN

Linux kernel >= 3.15 provides "open file description locks", also known as "file-private POSIX locks". Use them when available.

start => FILEPOS

type => F_RDLCK|F_WRLCK|F_UNLCK

wait => BOOLEAN

whence => SEEK_SET|SEEK_CUR|SEEK_END

example:

setfd_lock \*IN, type => F_WRLCK, wait => 1
    or die "cannot lock IN: $!\n";

setfd_notify($fd|$fh, $flags)

Command F_NOTIFY.

example:

my $d = openfd('/etc', O_RDONLY|O_DIRECTORY) or die $!;
setfd_notify($d, DN_ACCESS|DN_CREATE|DN_MULTISHOT) or die $!;

setfd_owner($fd|$fh, $pid, %options)

Commands F_GETOWN and F_GETOWN_EX. The _EX version is attempted if provided.

-Option--Default
 type    <looks at sign>

type => F_OWNER_TID|F_OWNER_PID|F_OWNER_PGRP

example:

setfd_owner($fh, $pid) or die $!;
setfd_owner($fh, $pid, type => F_OWNER_TID) or die $!;
setfd_owner($fh, -9);  # $pid=9, type=F_OWNER_PGRP

setfd_pipe_size($fd|$fh, $size)

Command F_SETPIPE_SZ.

example:

setfd_pipe_size($pipe, 16384) or die $!;

setfd_signal($fd|$fh, $signal)

Command F_SETSIG.

example:

setfd_signal(\*STDOUT, SIGINT) or die $!;

CONSTANTS

The following constants are exported, shown here with the values discovered during installation of this module.

The constant names for this fcntl module are inserted here during installation.

SEE ALSO

This module is part of POSIX-1003 distribution version 1.02, built on November 10, 2020. Website: http://perl.overmeer.net/CPAN. The code is based on POSIX, which is released with Perl itself. See also POSIX::Util for additional functionality.

COPYRIGHTS

Copyrights 2011-2020 on the perl code and the related documentation by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://dev.perl.org/licenses/