=head1 NAME

POSIX::Util - Extends

=head1 INHERITANCE

 POSIX::Util
   is a Exporter

=head1 SYNOPSIS

  use POSIX::Util;

  use POSIX::1003::FdIO qw(openfd O_RDONLY);
  my $fd   = openfd($fn, O_RDONLY);
  defined $fd or die $!;          # $fd is valid!
  my $data = readfd_all $fd, undef, 1;
  defined $data or die $!;

  writefd_all $out, $bytes, 1
      or die "write to $outfile failed: $!\n";

=head1 DESCRIPTION

This module collects some functions which are very often needed when working
on the low level of the POSIX interface.  The POSIX::1003 module is are
pure as possible, following the standard... this Util module adds some
convenience (at least has that intention).

=head1 FUNCTIONS

=head2 POSIX::1003::FdIO additions

=over 4

=item B<readfd_all>(FD, [SIZE, [DO_CLOSE]])

Read all remaining bytes from the FD.  At most SIZE bytes are read,
which defaults to SSIZE_MAX.

The maximum SIZE would be SSIZE_MAX, but POSIX.xs pre-allocs a buffer
with that size, so 2^64 is too large. We will read in convenient

  my $in = openfd $filename, O_RDONLY;
  defined $in or die "cannot open $filename to read: $!\n";

  my $d  = readfd_all $in, undef, 1;
  my $d  = readfd_all $in;
  defined $d or die "cannot read from $filename: $!\n";

=item B<writefd_all>(FD, BYTES, [DO_CLOSE])

Be sure that BYTES have the utf-8 flag off! We are working with bytes
here, not strings.  Returns undef if something went wrong (error in C<$!>),
otherwise the length of BYTES.

The FD will get closed when DO_CLOSE is provided and true.

example: 

  my $out = creatfd $outfile, 0600;
  writefd_all $out, $bytes, 1
      or die "write to $outfile failed: $!\n";

=back

=head1 SEE ALSO

This module is part of POSIX-Util distribution version 0.10,
built on July 26, 2012. Website: F<http://perl.overmeer.net>

=head1 LICENSE

Copyrights 2012 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>

