=encoding utf8

=head1 NAME

POSIX::1003::FS - POSIX for the file-system

=head1 SYNOPSIS

  use POSIX::1003::FS ':access';
  if(access $fn, R_OK) # $fn is readible?

  use POSIX::1003::FS qw(mkfifo :stat);
  mkfifo($path, S_IRUSR|S_IWUSR) or die $!;

  # Absorbed from Unix::Mknod
  use POSIX::1003::FS qw(mknod major minor makedev);
  use File::stat
  my $st    = stat '/dev/null';
  my $major = major $st->rdev;
  my $minor = minor $st->rdev;
  mknod '/tmp/special', S_IFCHR|0600, makedev($major,$minor+1);

=head1 DESCRIPTION

You may also need L<POSIX::1003::Pathconf|POSIX::1003::Pathconf>.

=head1 FUNCTIONS

=head2 Standard POSIX

=over 4

=item B<access>($filename, $flags)

Read C<man filetest> before you start using this function!
Use the C<*_OK> constants for $flags.

=item B<lchown>($uid, $gid, $filenames)

Like C<chown()>, but does not follow symlinks when encountered. Returns
the number of files successfully changed.

B<Be Warned> that the POSIX specification uses different parameter
order. For Perl was decided to accept a list of filenames.  Passing more
than one filename, however, hinders correct error reporting.

  # POSIX specification:
  # int lchown(const char *path, uid_t owner, gid_t group);

  # Perl core implementation:
  my $successes = chown($uid, $gid, @filenames);

  use POSIX;
  POSIX::lchown($uid, $gid, $filename) or die $!;

  use POSIX::1003::FS 'lchown';
  my @successes = lchown($uid, $gid, @filenames);

=item B<mkdir>( [$filename [$mask]] )

Simple C<CORE::mkdir()>

=item B<mkfifo>($filename, $mode)

=item B<mknod>($path, $mode, $device)

Create a special device node on $path. Useful symbols for $mode can be
collected from Fcntl (import tag C<:mode>).  The $device number is
a combination from the type (I<major> number), a sequence number and
usage information (combined in a I<minor> number).

=item B<rename>($oldname, $newname)

[0.93] Give a file or directory a new name, the basis of the UNIX C<mv>
('move') command.  This will use C<CORE::rename()>. 

B<Be warned> that Window's C<rename> implementation will fail when
$newname exists.  That behavior is not POSIX compliant.  On many platforms
(especially the older), a C<rename> between different partitions is not
allowed.

=item B<utime>($atime, $mtime, $filenames)

Simply C<CORE::utime()>

B<Be Warned> that C<POSIX.pm> uses a different parameter order than CORE.

  POSIX::utime($filename, $atime, $mtime);
  CORE::utime($atime, $mtime, @filenames);

=back

=head2 Additional

=over 4

=item B<S_ISBLK>($mode)

=item B<S_ISCHR>($mode)

=item B<S_ISDIR>($mode)

example: 

  use File::stat 'stat';
  if(S_ISDIR(stat($fn)->mode)) ...

  if(S_ISDIR((lstat $fn)[2])) ...

=item B<S_ISFIFO>($mode)

=item B<S_ISLNK>($mode)

=item B<S_ISREG>($mode)

=item B<S_ISSOCK>($mode)

=item B<S_ISVTX>($mode)

=item B<S_ISWHT>($mode)

=item B<major>($device)

=item B<makedev>($major, $minor)

Combine $major and $minor into a single DEVICE number.

 my $device      = (stat $filename)[6];
 my $device_type = major $device;
 my $sequence_nr = minor $device;

 my $device = makedev $major, $minor;
 mknod $specialfile, $mode, $device;

=item B<minor>($device)

=back

=head1 CONSTANTS

The following constants are exported, shown here with the values
discovered during installation of this module.  When you ask for
C<:constants>, you get all, but they are also grouped by tag.

=head2 export tag :stat

Export POSIX::1003::FS subroutine stat and POSIX::1003::FS subroutine lstat including their related constants.

=for comment
#TABLE_FSYS_STAT_START

  S_IFBLK   24576       S_IFSOCK  49152       S_IWGRP   16
  S_IFCHR   8192        S_IRGRP   32          S_IWOTH   2
  S_IFDIR   16384       S_IROTH   4           S_IWUSR   128
  S_IFIFO   4096        S_IRUSR   256         S_IXGRP   8
  S_IFLNK   40960       S_IRWXG   56          S_IXOTH   1
  S_IFMT    61440       S_IRWXO   7           S_IXUSR   64
  S_IFREG   32768       S_IRWXU   448         

=for comment
#TABLE_FSYS_STAT_END

=head2 export tag :access

Exports function L<access()|POSIX::1003::FS/"Standard POSIX"> plus its related constants.

=for comment
#TABLE_FSYS_ACC_START

  F_OK          0       NAME_MAX      255     W_OK          2
  FILENAME_MAX  4096    PATH_MAX      4096    X_OK          1
  MAX_CANON     255     R_OK          4       

=for comment
#TABLE_FSYS_ACC_END

=head2 export tag :perms

Load only the permission flags, and related functions L<mkfifo()|POSIX::1003::FS/"Standard POSIX">, L<mknod()|POSIX::1003::FS/"Standard POSIX">,
L<mkdir()|POSIX::1003::FS/"Standard POSIX">, and L<lchown()|POSIX::1003::FS/"Standard POSIX">.  Also, the common C<S_IS*> C-level macro are
provided as function.

=for comment
#TABLE_FSYS_PERM_START

  S_IFBLK   24576       S_IFSOCK  49152       S_IWGRP   16
  S_IFCHR   8192        S_IRGRP   32          S_IWOTH   2
  S_IFDIR   16384       S_IROTH   4           S_IWUSR   128
  S_IFIFO   4096        S_IRUSR   256         S_IXGRP   8
  S_IFLNK   40960       S_IRWXG   56          S_IXOTH   1
  S_IFMT    61440       S_IRWXO   7           S_IXUSR   64
  S_IFREG   32768       S_IRWXU   448         

=for comment
#TABLE_FSYS_PERM_END

=head2 export tag :glob

The POSIX::1003::FS subroutine glob and POSIX::1003::FS subroutine fnmatch related constants.

=for comment
#TABLE_FSYS_GLOB_START

  GLOB_ALTDIRFUNC   512           GLOB_NOMAGIC      2048
  GLOB_APPEND       32            GLOB_NOMATCH      3
  GLOB_BRACE        1024          GLOB_NOSORT       4
  GLOB_DOOFFS       8             GLOB_NOSPACE      1
  GLOB_ERR          1             GLOB_ONLYDIR      8192
  GLOB_MAGCHAR      256           GLOB_PERIOD       128
  GLOB_MARK         2             GLOB_TILDE        4096
  GLOB_NOCHECK      16            GLOB_TILDE_CHECK  16384
  GLOB_NOESCAPE     64            

=for comment
#TABLE_FSYS_GLOB_END

=head1 SEE ALSO

This module is part of POSIX-1003 distribution version 0.99_02,
built on February 03, 2015. 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-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 F<http://www.perl.com/perl/misc/Artistic.html>

