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, $fcntl->{F_LOCK}) ...
lockf $fd, $fcntl->{F_ULOCK};

Additional

fcntl_dup($fd|$fh, %options)

Functions $fcntl->{F_DUPFD} and $fcntl->{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, function $fcntl->{F_GETFD}.

getfd_flags($fd|$fh)

Get the file status flags and access modes, function $fcntl->{F_GETFL}.

example:

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

getfd_islocked($fd|$fh, %options)

Function $fcntl->{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)

Function $fcntl->{F_GETLEASE}.

example:

my $lease = getfd_lease(\*STDIN) or die $!;
if($lease != $fcntl->{F_RDLCK}) ...

getfd_owner($fd|$fh, %options)

Function $fcntl->{F_GETOWN} or $fcntl->{F_GETOWN_EX}.

example:

my ($type, $pid) = getfd_owner($fd);
defined $type or die $!;
if($type==$fcntl->{F_OWNER_PGRP}) ...

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

getfd_pipe_size($fd|$fh)

Function $fcntl->{F_GETPIPE_SZ}.

example:

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

getfd_signal($fd|$fh)

Function $fcntl->{F_GETSIG}.

example:

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

setfd_control($fd|$fh, $flags)

Change the file descriptor flags, function $fcntl->{F_SETFD}.

setfd_flags($fd|$fh, $flags)

Change the file status flags and access modes, function $fcntl->{F_SETFL}.

setfd_lease($fd|$fh, $flags)

Function $fcntl->{F_SETLEASE}.

example:

setfd_lease(\*STDOUT, $fcntl->{F_WRLCK}) or die $!;

setfd_lock($fd|$fh, %options)

Functions $fcntl->{F_SETLK} and $fcntl->{F_SETLKW}: request a lock for (a section of) a file.

-Option --Default
 len      <until end of file>
 private  <false>
 start    0
 type     $fcntl->{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 => $fcntl->{F_RDLCK}|$fcntl->{F_WRLCK}|$fcntl->{F_UNLCK}

wait => BOOLEAN

whence => SEEK_SET|SEEK_CUR|SEEK_END

example:

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

setfd_notify($fd|$fh, $flags)

Function $fcntl->{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)

Function $fcntl->{F_GETOWN} or $fcntl->{F_GETOWN_EX}. The _EX version is attempted if provided.

-Option--Default
 type    <looks at sign>

type => $fcntl->{F_OWNER_TID}|$fcntl->{F_OWNER_PID}|$fcntl->{F_OWNER_PGRP}

example:

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

setfd_pipe_size($fd|$fh, $size)

Function $fcntl->{F_SETPIPE_SZ}.

example:

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

setfd_signal($fd|$fh, $signal)

Function $fcntl->{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 0.99_03, built on February 07, 2015. Website: http://perl.overmeer.net. The code is based on POSIX, which is released with Perl itself. See also POSIX::Util for additional functionality.

COPYRIGHTS

Copyrights 2011-2015 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://www.perl.com/perl/misc/Artistic.html