The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

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

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);

DESCRIPTION

You may also need POSIX::1003::Pathconf.

FUNCTIONS

Standard POSIX

access($filename, $flags)

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

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;
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 glob(). Various system shells (sh, bash, tsh, etc) use this same function with different flags. This function provides any possible combination.

BE WARNED that function returns bytes: file names are not printable strings because the encoding used for file names on disk is not defined (on UNIXes). Read more in "Filenames to string"

BE WARNED that File::Glob does not use the system's libc glob(), but includes the bare code of that implementation. For that reason, it's bsd_glob() does work on Windows and other platforms in the same way. Also, 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 on_error callback.

 -Option  --Default
  flags     GLOB_NOSORT|GLOB_NOESCAPE|GLOB_BRACE
  on_error  undef
  unique    <false>
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)

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 not thread safe

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.

example:

  my ($err, $fns) = glob(\@roots, flags => GLOB_NOSORT|GLOB_MARK,
      on_error => sub { warn "skip $_[0]: error $_[1]"; 0} )
lchown($uid, $gid, $filenames)

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

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);
lstat( [$fh|$fn|$dirfh] )

Simply CORE::lstat(). See also stat()

mkdir( [$filename [$mask]] )

Simple CORE::mkdir()

mkfifo($filename, $mode)
mknod($path, $mode, $device)

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

rename($oldname, $newname)

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

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

stat( [$fh|$fn|$dirfh] )

Simply CORE::stat(). See also lstat()

utime($atime, $mtime, $filenames)

Simply CORE::utime()

Be Warned that POSIX.pm uses a different parameter order than CORE.

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

Additional

S_ISBLK($mode)
S_ISCHR($mode)
S_ISDIR($mode)

example:

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

  if(S_ISDIR((lstat $fn)[2])) ...
S_ISFIFO($mode)
S_ISLNK($mode)
S_ISREG($mode)
S_ISSOCK($mode)
S_ISVTX($mode)
S_ISWHT($mode)
major($device)
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;
minor($device)

CONSTANTS

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

export tag :stat

Export stat() and lstat() including their related constants. Besides, the node related functions mkfifo(), mknod(), mkdir(), and lchown(). Also, the common S_IS* C-level macro are provided as function.

  During installation, a symbol table will get inserted here.

export tag :access

Exports function access() plus its related constants.

  During installation, a symbol table will get inserted here.

export tag :glob

The glob() and fnmatch() related constants.

  During installation, a symbol table will get inserted here.

SEE ALSO

This module is part of POSIX-1003 distribution version 1.02, built on November 10, 2020. Website: http://perl.overmeer.net/CPAN. The code is based on POSIX, which is released with Perl itself. See also POSIX::Util for additional functionality.

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 http://dev.perl.org/licenses/