NAME

Chj::xperlfunc

SYNOPSIS

 my $pid= xspawn @files;
 print "Did it!\n";
 wait;
 print "The process (was pid $pid) gave ".($?>>8)."\n";

DESCRIPTION

Wrappers around core functions that throw exceptions on errors. Plus some simple utilities, exported optionally (explicitely or as part of the ":all" tag.)

FUNCTIONS

xsystem(..)

Croaks if the command could not be started (i.e. system gave -1). Returns the exit code of the program (== $?);

xxsystem(..)

Same as xsystem but also croaks if $? != 0.

xsystem_safe(..)

xxsystem_safe(..)

Same as the *xsystem calls but never run a shell, even if only one argument is given.

ADDITIONAL FUNCTIONS

These are exported by default.

xstat(path)

xlstat(path)

Xstat(path)

Xlstat(path)

These are wrappers around stat; the x* functions die, the X* ones return undef on ENOENT errors (and still croak on other errors like permission problems). When successful, they return objects (based on array with the stat return values) with accessor methods.

If $Chj::xperlfunc::time_hires is true, these will return floating point number strings for time stamps.

xlocaltime() or xlocaltime(unixtime)

These are wrappers around localtime; it never dies, but returns objects (based on an array with the localtime values) with accessor methods (including chainable setters). Additionally to the normal accessors, 'Year' and 'Mon' exist, which are in the "normal" (19xx..203x, 1..31) ranges, and 'Wday' which is 1..7 starting on Sunday and 'wDay' which is 0..6 starting on Monday. They also have a unixtime function to convert back to unixtime--this requires Time::Local to be loaded explicitely.

SPECIAL FUNCTIONS

These may be imported explicitely on demand.

xfork_(&)

Forks then runs the passed thunk in the child. The child process captures any uncaught exceptions and runs exit(1), otherwise upon ending the thunk exit(0).

xLmtimed($), XLmtimed($)

Those call lstat first, then if it's a symlink, also stat, then return an object with an mtime method that returns the newer mtime of the two. Other methods are is_link (about the original path) and is_dir and is_file (about the target path).

NOTE: those only call lstat and stat once, they don't check whether the target is reached through several intermediate links or whether any directory in any of the paths has newer mtime. Thus the result can't be relied on for security (well, couldn't anyway since mtime can be set, of course).

xLmtime($), XLmtime($)

Same as xLmtimed, XLmtimed but return the mtime value (or undef) instead of a wrapper object.

xspawn($;)

Like xsystem, but returns as soon as the command has been started successfully, leaving it running in the background. You may and should wait() for it some time, you may also get SIGCHLD.

xlaunch($;)

Launch a program fully in the background, in a separate session, and with double fork so that we don't need to (and never may) wait for it ever. Using a pipe, it can still find out if the launch was successful or not.

xmvmkdir(first,newplace [,strict])

Move directory 'first' to 'newplace', then create a new empty dir at place 'first' with same permissions as 'newplace'. Only root can recreate owners different than current user and groups that the user is not part in, of course. If 'strict' is true, croaks if it can't recreate all permission details.

pathref = xtmpdir_with_paragon(pathtoexistingdir [,strict])

Create new directory using pathtoexistingdir as paragon. The new directoy is placed into the same parent dir, with a dot prepended and .tmp and a random number appended. The permissions are recreated. A reference of t he path to the new directory is returned. (Reason to use a reference: it's a lightweight object; upon deleting the last reference, it will try to remove the tmpdir if empty.)

xmkdir_with_paragon UNTESTED

xlinkunlink $source,$target

Has the same effect as xrename $source,$target except that it won't overwrite $target if it already exists. This is done by using link and unlink instead of rename.

xxcarefulrename $source,$target

xlinkunlink doesn't work for directories, or not always under grsec. xxcarefulrename does resort to rename if hardlinks don't work. But note: this is only careful, not guaranteed to be safe.

xlinkreplace $source,$target

This makes a new hardlink from source to target, potentially replacing a previous target. All the same it does the replace atomically. (It works by creating a link to a temporary location then rename.) (Hm, strange function name?)

xfileno $string_or_FH

Does work with both filehandles and integer strings. Croaks if it's neither or there's an error.

basename $pathstring [,$suffix(es) [,$insensitive]]

Same as the shell util of the same name, except that it croaks in a few cases (when an empty string is given, or when the given suffix doesn't match).

dirname $pathstring

Same as the shell util (or about as my old FolderOfThisFile function), except that it croaks if dirname of "/" or "." is requested.

xmkdir_p $pathstring

Works like unix's "mkdir -p": return false if the directory already exists, true if it (and, if necessary, it's parent(s)) has(/have) been created, croaks if some error happens on the way.

xlink_p $frompath, $topath

xlink's $frompath to $topath but

NOTE

This is alpha software! Read the status section in the package README or on the website.