File Coverage

blib/lib/Filesys/POSIX/Userland.pm

Criterion	Covered	Total	%
statement	66	66	100.0
branch	12	12	100.0
condition	3	3	100.0
subroutine	14	14	100.0
pod	7	7	100.0
total	102	102	100.0

# Copyright (c) 2014, cPanel, Inc.
# All rights reserved.
# http://cpanel.net/
#
# This is free software; you can redistribute it and/or modify it under the same
# terms as Perl itself.  See the LICENSE file for further details.

package Filesys::POSIX::Userland;

use strict;
use warnings;

use Filesys::POSIX::Bits;
use Filesys::POSIX::Module ();
use Filesys::POSIX::Path   ();

use Carp qw(confess);

my @METHODS = qw(
  _find_inode_path mkpath getcwd realpath opendir readdir closedir touch
);

Filesys::POSIX::Module->export_methods( __PACKAGE__, @METHODS );

=head1 NAME

Filesys::POSIX::Userland - Provide implementations for higher-level, "userland"
functionality in L

=head1 DESCRIPTION

This module is a mixin imported by L into its own namespace, and
provides a variety of higher-level calls to supplement the normal suite of
system calls provided in L itself.

=head1 METHODS

=over

=cut

sub _find_inode_path {
    my ( $self, $start ) = @_;
    my $inode = $self->{'vfs'}->vnode($start);
    my @ret;

    while ( my $dir = $self->{'vfs'}->vnode($inode)->{'parent'} ) {
        my $directory = $dir->directory;

        foreach my $item ( $directory->list ) {
            next if $item eq '.' || $item eq '..';
            next
              unless $self->{'vfs'}->vnode( $directory->get($item) ) == $self->{'vfs'}->vnode($inode);

            push @ret, $item;
            $inode = $dir;
        }
    }

    return '/' . join( '/', reverse @ret );
}

=item C<$fs-Emkpath($path)>

=item C<$fs-Emkpath($path, $mode)>

Similar to the C<-p> flag that can be passed to L, this
method attempts to create a hierarchy of directories specified in C<$path>.
Each path component created will be made with the mode specified by C<$mode>, if
any, if a directory in that location does not already exist.  Exceptions will be
thrown if one of the items along the path hierarchy exists but is not a
directory.

A default mode of 0777 is assumed; only the permissions field of C<$mode> is
used when it is specified.  In both cases, the mode specified is modified with
exclusive OR by the current umask value.

=cut

sub mkpath {
    my ( $self, $path, $mode ) = @_;
    my $perm = $mode ? $mode & ( $S_IPERM | $S_IPROT ) : $S_IPERM ^ $self->{'umask'};
    my $hier = Filesys::POSIX::Path->new($path);
    my $dir  = $self->{'cwd'};

    while ( $hier->count ) {
        my $item = $hier->shift;

        unless ($item) {
            $dir = $self->{'root'};
            next;
        }

        my $directory = $dir->directory;
        my $inode     = $self->{'vfs'}->vnode( $directory->get($item) );

        if ($inode) {
            $dir = $inode;
        }
        else {
            $dir = $dir->child( $item, $perm | $S_IFDIR );
        }
    }

    return $dir;
}

=item C<$fs-Egetcwd>

Returns a string representation of the current working directory.

=cut

sub getcwd {
    my ($self) = @_;

    return $self->_find_inode_path( $self->{'cwd'} );
}

=item C<$fs-Erealpath($path)>

Returns a string representation of the full, true and original path of the
inode specified by C<$path>.

Using C<$fs-Estat>, the inode of C<$path> is resolved, then starting at that
inode, each subsequent inode's name is found from its parent and appended to a
list of path components.

=cut

sub realpath {
    my ( $self, $path ) = @_;
    my $inode = $self->stat($path);

    return $self->_find_inode_path($inode);
}

=item C<$fs-Eopendir($path)>

Returns a newly opened directory handle for the item pointed to by C<$path>.
Using other methods in this module, the directory can be read and closed.

=cut

sub opendir {
    my ( $self, $path ) = @_;

    my $directory = $self->stat($path)->directory;
    $directory->open;

    return $directory;
}

=item C<$fs-Ereaddir($directory)>

Read the next member of the directory passed.  Returns undef if there are no
more entries to be read.

=cut

sub readdir {
    my ( $self, $directory ) = @_;

    return $directory->read unless wantarray;

    my @ret;

    while ( defined( my $item = $directory->read ) ) {
        push @ret, $item;
    }

    return @ret;
}

=item C<$fs-Eclosedir($directory)>

Closes the directory handle for reading.

=cut

sub closedir {
    my ( $self, $directory ) = @_;
    return $directory->close;
}

=item C<$fs-Etouch($path)>

Acts like the userland utility L.  Uses C<$fs-Eopen>
with the C<$O_CREAT> flag to open the file specified by C<$path>, and
immediately closes the file descriptor returned.  This causes an update of the
inode modification time for existing files, and the creation of new, empty files
otherwise.

=cut

sub touch {
    my ( $self, $path ) = @_;
    my $fd = $self->open( $path, $O_CREAT );
    my $inode = $self->fstat($fd);

    $self->close($fd);

    return $inode;
}

=back

=cut

1;

__END__