/ 
POSIX-1003-0.96
River stage one • 2 direct dependents • 2 total dependents
/ POSIX::1003::Fcntl

NAME

POSIX::1003::Fcntl - POSIX function fcntl

INHERITANCE

POSIX::1003::Fcntl
  is a POSIX::1003::Module

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.

See documentation in the base class.

METHODS

See documentation in the base class.

POSIX::1003::Fcntl->exampleValue(NAME)

See "METHODS" in POSIX::1003::Module

$obj->import()

See "METHODS" in POSIX::1003::Module

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)

Functions 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, function F_GETFD.

getfd_flags(FD|FH)

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

example:

my $flags = getfd_flags(fd);
if ((flags & O_ACCMODE) == O_RDWR)
getfd_islocked(FD|FH, OPTIONS)

Function 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 F_GETLEASE.

example:

my $lease = getfd_lease(\*STDIN) or die $!;
if($lease != F_RDLCK) ...
getfd_owner(FD|FH, OPTIONS)

Function F_GETOWN or 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)

Function F_GETPIPE_SZ.

example:

my $size = getfd_pipe_size($pipe) or die $!;
getfd_signal(FD|FH)

Function F_GETSIG.

example:

my $signal = getfd_signal(\*STDOUT) or die $!;
setfd_control(FD|FH, FLAGS)

Change the file descriptor flags, function F_SETFD.

setfd_flags(FD|FH, FLAGS)

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

setfd_lease(FD|FH, FLAGS)

Function F_SETLEASE.

example:

setfd_lease(\*STDOUT, F_WRLCK) or die $!;
setfd_lock(FD|FH, OPTIONS)

Functions F_SETLK and F_SETLKW: request a lock for (a section of) a file.

-Option--Default
 len     <until end of file>
 start   0
 type    F_RDLCK
 wait    <false>
 whence  SEEK_SET
len => BLOCK_LENGTH
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)

Function 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 F_GETOWN or 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)

Function F_SETPIPE_SZ.

example:

setfd_pipe_size($pipe, 16384) or die $!;
setfd_signal(FD|FH, SIGNAL)

Function 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.

DN_ACCESS        1              F_SETFL          4
DN_ATTRIB        32             F_SETLEASE       1024
DN_CREATE        4              F_SETLKW         7
DN_DELETE        8              F_SETOWN         8
DN_MODIFY        2              F_SETOWN_EX      15
DN_MULTISHOT     2147483648     F_SETPIPE_SZ     1031
DN_RENAME        16             F_SETSIG         10
F_DUPFD          0              F_TEST           3
F_DUPFD_CLOEXEC  1030           F_TLOCK          2
F_GETFD          1              F_ULOCK          0
F_GETFL          3              F_UNLCK          2
F_GETLEASE       1025           F_WRLCK          1
F_GETLK          5              FAPPEND          undef
F_GETOWN         9              FASYNC           undef
F_GETOWN_EX      16             FD_CLOEXEC       1
F_GETPIPE_SZ     1032           FNDELAY          undef
F_GETSIG         11             FNONBLOCK        undef
F_LOCK           1              LOCK_EX          2
F_NOTIFY         1026           LOCK_NB          4
F_RDLCK          0              LOCK_SH          1
F_SETFD          2              LOCK_UN          8

SEE ALSO

This module is part of POSIX-1003 distribution version 0.96, built on November 28, 2013. 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-2013 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