=encoding utf8

=head1 NAME

POSIX::1003::Fcntl - POSIX function fcntl

=head1 INHERITANCE

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

=head1 SYNOPSIS

  use POSIX::1003::Fcntl;

=head1 DESCRIPTION

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

See L<documentation in the base class|POSIX::1003::Module/"DESCRIPTION">.
 
=head1 METHODS

See L<documentation in the base class|POSIX::1003::Module/"METHODS">.
 
=over 4

=item POSIX::1003::Fcntl-E<gt>B<exampleValue>(NAME)

See L<POSIX::1003::Module/"METHODS">

=item $obj-E<gt>B<import>()

See L<POSIX::1003::Module/"METHODS">

=back

=head1 FUNCTIONS

=head2 Standard POSIX

=over 4

=item B<fcntl>(FD, FUNCTION, SCALAR)

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

=item B<flockfd>(FD, FLAGS)

Not standard POSIX, but available on many POSIX platforms.  Often
implemented as L<fcntl()|POSIX::1003::Fcntl/"Standard POSIX">, which is more complex to use.  On other
platforms implemented as separate OS feature.

Perl core provides a C<flock> which may hide plaform differences.
This C<flockfd> is the pure version.  Try to use L<setfd_lock()|POSIX::1003::Fcntl/"Additional">, which
is more portable and flexible.

example: 

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

=item B<lockf>(FD, FLAG, LENGTH)

Not standard POSIX, but available on many POSIX platforms.  Often
implemented via L<fcntl()|POSIX::1003::Fcntl/"Standard POSIX">, which is more complex to use.

example: 

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

=back

=head2 Additional

=over 4

=item B<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>

=over 2

=item close_on_exec => BOOLEAN

=back

example: 

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

=item B<getfd_control>(FD|FH)

Control the file descriptor flags, function F_GETFD.

=item B<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)

=item B<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 L<setfd_lock()|POSIX::1003::Fcntl/"Additional">.

example: 

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

=item B<getfd_lease>(FD|FH)

Function F_GETLEASE.

example: 

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

=item B<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 $!;

=item B<getfd_pipe_size>(FD|FH)

Function F_GETPIPE_SZ.

example: 

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

=item B<getfd_signal>(FD|FH)

Function F_GETSIG.

example: 

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

=item B<setfd_control>(FD|FH, FLAGS)

Change the file descriptor flags, function F_SETFD.

=item B<setfd_flags>(FD|FH, FLAGS)

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

=item B<setfd_lease>(FD|FH, FLAGS)

Function F_SETLEASE.

example: 

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

=item B<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

=over 2

=item len => BLOCK_LENGTH

=item start => FILEPOS

=item type => F_RDLCK|F_WRLCK|F_UNLCK

=item wait => BOOLEAN

=item whence => SEEK_SET|SEEK_CUR|SEEK_END

=back

example: 

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

=item B<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 $!;

=item B<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>

=over 2

=item type => F_OWNER_TID|F_OWNER_PID|F_OWNER_PGRP

=back

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

=item B<setfd_pipe_size>(FD|FH, SIZE)

Function F_SETPIPE_SZ.

example: 

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

=item B<setfd_signal>(FD|FH, SIGNAL)

Function F_SETSIG.

example: 

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

=back

=head1 CONSTANTS

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

=for comment
#TABLE_FCNTL_START

  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


=for comment
#TABLE_FCNTL_END





=head1 SEE ALSO

This module is part of POSIX-1003 distribution version 0.98,
built on December 03, 2013. Website: F<http://perl.overmeer.net>.  The code is based on L<POSIX>, which
is released with Perl itself.  See also L<POSIX::Util> for
additional functionality.

=head1 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 F<http://www.perl.com/perl/misc/Artistic.html>

