=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<fnmatch>( $pattern, $name, [$flags] )
Check whether $name matches $pattern, under control of $flags (FNM_*
constants). Do always check the return value for FNM_NOMATCH (true!!!)
example:
use POSIX::1003::FS ':glob';
next if fnmatch('a*', 'ABC', FNM_CASEFOLD)==FNM_NOMATCH;
=item B<glob>($pattern|\@patterns, %options)
Returns a list of file and directory names which match the $pattern
(or any of the @patterns), using the libc implementation of L<glob()|POSIX::1003::FS/"Standard POSIX">.
Various system shells (sh, bash, tsh, etc) use this same function with
different flags. This function provides any possible combination.
B<BE WARNED> that function returns bytes: file names are B<not
printable strings> because the encoding used for file names on disk is
not defined (on UNIXes). Read more in L</Filenames to string>
B<BE WARNED> that File::Glob does not use the system's libc C<glob()>,
but includes the bare code of that implementation. For that reason,
it's C<bsd_glob()> does work on Windows and other platforms in the same
way. Also, C<bsd_glob()> supports the non-posix '{}' syntax as BSD has.
It also adapts the defaults of the flags to match the default OS behavior.
On the other hand, File::Glob does not support the C<on_error> callback.
-Option --Default
flags GLOB_NOSORT|GLOB_NOESCAPE|GLOB_BRACE
on_error undef
unique <false>
=over 2
=item flags => INTEGER
There are many interesting flags to tune the expansion. Sorting should
happen in a locale context, so there is no use having glob() do it on
bytes. GLOB_APPEND will be used automatically, when needed. GLOB_DOOFFS
cannot be used (not needed)
=item on_error => CODE
What to do when an error is encountered. The CODE will be called with
the path causing the problem, and the error code. When you want the
search to continue, you have to return '0'.
This function is B<not thread safe>
=item unique => BOOLEAN
When you use patterns which overlap, you may want to remove doubles.
Still, this happens on bytes... there is a possibility that different
byte strings display the same in utf8 space.
=back
example:
my ($err, $fns) = glob(\@roots, flags => GLOB_NOSORT|GLOB_MARK,
on_error => sub { warn "skip $_[0]: error $_[1]"; 0} )
=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<lstat>( [$fh|$fn|$dirfh] )
Simply C<CORE::lstat()>. See also L<stat()|POSIX::1003::FS/"Standard POSIX">
=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<stat>( [$fh|$fn|$dirfh] )
Simply C<CORE::stat()>. See also L<lstat()|POSIX::1003::FS/"Standard POSIX">
=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 L<stat()|POSIX::1003::FS/"Standard POSIX"> and L<lstat()|POSIX::1003::FS/"Standard POSIX"> including their related constants.
Besides, the node 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_STAT_START
During installation, a symbol table will get inserted here.
=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
During installation, a symbol table will get inserted here.
=for comment
#TABLE_FSYS_ACC_END
=head2 export tag :glob
The L<glob()|POSIX::1003::FS/"Standard POSIX"> and L<fnmatch()|POSIX::1003::FS/"Standard POSIX"> related constants.
=for comment
#TABLE_FSYS_GLOB_START
During installation, a symbol table will get inserted here.
=for comment
#TABLE_FSYS_GLOB_END
=head1 SEE ALSO
This module is part of POSIX-1003 distribution version 1.02,
built on November 10, 2020. Website: F<http://perl.overmeer.net/CPAN>. 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-2020 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://dev.perl.org/licenses/>