Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Paranoid::Glob(3)     User Contributed Perl Documentation    Paranoid::Glob(3)

NAME
       Paranoid::Glob -	Paranoid Glob objects

VERSION
       $Id: lib/Paranoid/Glob.pm, 2.08 2020/12/31 12:10:06 acorliss Exp	$

SYNOPSIS
	   $obj	= Paranoid::Glob->new(
		  globs	      => [ qw(/lib/* /sbin/* /etc/foo.conf) ],
		  literals    => [ qw(/tmp/{sadssde-asdfak}) ],
		  );

	   print "Expanded globs:\n\t",	join("\n\t", @$obj);

	   $rv = $obj->addGlobs(qw(/etc/* /bin/*));
	   $rv = $obj->addLiterals(qw(/etc/foo.conf));

	   $obj->consolidate;

	   @existing	   = $obj->exists;
	   @readable	   = $obj->readable;
	   @writable	   = $obj->writable;
	   @executable	   = $obj->executable;
	   @owned	   = $obj->owned;
	   @directories	   = $obj->directories;
	   @files	   = $obj->files;
	   @symlinks	   = $obj->symlinks;
	   @pipes	   = $obj->pipes;
	   @sockets	   = $obj->sockets;
	   @blockDevs	   = $obj->blockDevs;
	   @charDevs	   = $obj->charDevs;

	   $obj->recurse(1, 1);

DESCRIPTION
       The primary purpose of these objects is to allow	an easy	way to detaint
       a list of files and/or directories while	performing shell expansion of
       names.  It does this with a caveat, however.  If	a given	file or
       directory name exists on	the file system	as a literal string
       (regardless of whether it has shell expansion characters	in it) it will
       be added	as such.  It is	only filtered through bsd_glob if it does not
       exist on	the file system.

       The objects can also be created with instructions to explicitly treat
       all names as literal strings.

       Any undef or zero-length	strings	passed in the files array are silently
       removed.

       As a convenience	subsets	of the expanded	files can be returned based on
       the common stat/lstat tests.  Please note the obvious caveats, however:
       asking for a list of directories	will fail to list directories if the
       effective user does not have privileges to read the parent directory,
       etc.  This is no	different than performing '-d',	etc., directly.	 If
       you care	about privilege/permission issues you shouldn't	use these
       methods.

       An additional method (recurse) falls outside of what a globbing
       construct should	do, but	it seemed too useful to	leave out.

SUBROUTINES/METHODS
   new
	   $obj	= Paranoid::Glob->new(
		  globs	      => [ qw(/lib/* /sbin/* /etc/foo.conf) ],
		  literals    => [ qw(/tmp/{sadssde-asdfak}) ],
		  );

       This class method creates a Paranoid::Glob object.  It can be
       constructed with	optional literal strings and/or	globs to expand.  All
       are filtered through a [[:print:]] regex	for detainting.	 Any undefined
       or zero-length strings are silently removed from	the arrays.

       The object reference is a blessed array reference, which	is populated
       with the	expanded (or literal) globs, making it easy to iterate over
       the final list.

       If any entry in the globs array fails to	detaint	this method will
       return undef instead of an object reference.

   addGlobs
	   $rv = $obj->addGlobs(qw(/etc/* /bin/*));

       Adds more globs to the object that are detainted	and filtered through
       bsd_glob.  Returns false	if any strings fail to detaint.	 All undefined
       or zero-length strings are silently removed.

   addLiterals
	   $rv = $obj->addLiterals(qw(/etc/foo.conf));

       Adds more literal strings to the	object that are	detainted.  Returns
       false if	any strings fail to detaint.  All undefined or zero-length
       strings are silently removed.

   consolidate
	   $obj->consolidate;

       This method removes redundant entries and lexically sorts the contents
       of the glob.

   exists
	   @existing	   = $obj->exists;

       This object method returns a list of all	entries	that currently exist
       on the filesystem.  In the case of a symlink that exists	but links to a
       nonexistent file	it returns the symlink as well.

   readable
	   @readable	   = $obj->readable;

       This method returns a list of all entries that are currently readable
       by the effective	user.  In the case of a	symlink	it returns the symlink
       only if the target of the symlink is readable, just as a	normal stat or
       -r function would.

   writable
	   @writable	   = $obj->writable;

       This method returns a list of all entries that are currently writable
       by the effective	user.  In the case of a	symlink	it returns the symlink
       only if the target of the symlink is writable, just as a	normal stat or
       -w function would.

   executable
	   @executable	   = $obj->executable;

       This method returns a list of all entries that are currently executable
       by the effective	user.  In the case of a	symlink	it returns the symlink
       only if the target of the symlink is executable,	just as	a normal stat
       or -x function would.

   owned
	   @owned	   = $obj->owned;

       This method returns a list of all entries that are currently owned by
       the effective user.  In the case	of a symlink it	returns	the symlink
       only if the target of the symlink is owned, just	as a normal stat or -o
       function	would.

   directories
	   @directories	   = $obj->directories;

       This method returns a list of all the directories.  In the case of a
       symlink it returns the symlink if the target of the symlink is a
       directory, just as a normal stat	or -d function would.

   files
	   @files	   = $obj->files;

       This method returns a list of all the files.  In	the case of a symlink
       it returns the symlink if the target of the symlink is a	file, just as
       a normal	stat or	-f function would.

   symlinks
	   @symlinks	   = $obj->symlinks;

       This method returns a list of all the symlinks.

   pipes
	   @pipes	   = $obj->pipes;

       This method returns a list of all the pipes.  In	the case of a symlink
       it returns the symlink if the target of the symlink is a	pipe, just as
       a normal	stat or	-p function would.

   sockets
	   @sockets	   = $obj->sockets;

       This method returns a list of all the sockets.  In the case of a
       symlink it returns the symlink if the target of the symlink is a
       socket, just as a normal	stat or	-S function would.

   blockDevs
	   @blockDevs	   = $obj->blockDevs;

       This method returns a list of all the block device nodes.  In the case
       of a symlink it returns the symlink if the target of the	symlink	is a
       block device node, just as a normal stat	or -b function would.

   charDevs
	   @charDevs	   = $obj->charDevs;

       This method returns a list of all the character device nodes.  In the
       case of a symlink it returns the	symlink	if the target of the symlink
       is a character device node, just	as a normal stat or -c function	would.

   recurse
	   $obj->recurse;
	   $obj->recurse(1);
	   $obj->recurse(1, 1);

       This method with	recursively load all filesystem	entries	underneath any
       directories already listed in the object.  It returns true upon
       completion, or false if any errors occurred (such as Permission
       Denied).

       Two optional boolean arguments can be passed to it:

	 Option1:	 Follow	Symlinks
	 Option2:	 Include "Hidden" directories

       Both options are	false by default.  If Option1 (Follow Symlinks)	is
       true any	symlinks pointing to directories will be recursed into as
       well.  Option2 in its default false setting excludes dot	files or
       directories just	as normal shell	expansion would.  Setting it to	true
       causes it to include (and recurse into) hidden files and	directories.

DEPENDENCIES
       o   Carp

       o   Errno

       o   Fcntl

       o   File::Glob

       o   Paranoid

       o   Paranoid::Debug

BUGS AND LIMITATIONS
AUTHOR
       Arthur Corliss (corliss@digitalmages.com)

LICENSE	AND COPYRIGHT
       This software is	free software.	Similar	to Perl, you can redistribute
       it and/or modify	it under the terms of either:

	 a)	the GNU	General	Public License
		<https://www.gnu.org/licenses/gpl-1.0.html> as published by the
		Free Software Foundation <http://www.fsf.org/>;	either version 1
		<https://www.gnu.org/licenses/gpl-1.0.html>, or	any later version
		<https://www.gnu.org/licenses/license-list.html#GNUGPL>, or
	 b)	the Artistic License 2.0
		<https://opensource.org/licenses/Artistic-2.0>,

       subject to the following	additional term:  No trademark rights to
       "Paranoid" have been or are conveyed under any of the above licenses.
       However,	"Paranoid" may be used fairly to describe this unmodified
       software, in good faith,	but not	as a trademark.

       (c) 2005	- 2020,	Arthur Corliss (corliss@digitalmages.com) (tm) 2008 -
       2020, Paranoid Inc. (www.paranoid.com)

perl v5.32.1			  2020-12-31		     Paranoid::Glob(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | SUBROUTINES/METHODS | DEPENDENCIES | BUGS AND LIMITATIONS | AUTHOR | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Paranoid::Glob&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help