public package Foswiki::Sandbox

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

Child packagesChild packages

public package Foswiki::Sandbox

This package provides an interface to the outside world. All calls to system functions, or handling of file names, should be brokered by the sysCommand function in this package.

Since date indicates where functions or parameters have been added since the baseline of the API (TWiki release 4.2.3). The date indicates the earliest date of a Foswiki release that will support that function or parameter.

Deprecated date indicates where a function or parameters has been deprecated. Deprecated functions will still work, though they should not be called in new plugins and should be replaced in older plugins as soon as possible. Deprecated parameters are simply ignored in Foswiki releases after date.

Until date indicates where a function or parameter has been removed. The date indicates the latest date at which Foswiki releases still supported the function or parameter.

StaticMethod untaintUnchecked ( $string ) → $untainted

Untaints $string without any checks. If $string is undefined, return undef.

This function doesn't perform any checks on the data being untainted. Callers must ensure that $string does not contain any dangerous content, such as interpolation characters, if it is to be used in potentially unsafe operations.

StaticMethod untaint ( $datum, \&method, ... ) → $untainted

Calls &$method($datum, ...) and if it returns a non-undef result, returns that result after untainting it. Otherwise returns undef.

\&method can indicate a validation problem in a couple of ways. First, it can throw an exception. Second, it can return undef, which then causes the untaint function to return undef.

StaticMethod validateWebName($name) → $web

Check that the name is valid for use as a web name. Method used for validation with untaint(). Returns the name, or undef if it is invalid.

StaticMethod validateTopicName($name) → $topic

Check that the name is valid for use as a topic name. Method used for validation with untaint(). Returns the name, or undef if it is invalid.

StaticMethod validateAttachmentName($name) → $attachment

Check that the name is valid for use as an attachment name. Method used for validation with untaint(). Returns the name, or undef if it is invalid.

Note that the name may contain path separators. This is to permit validation of an attachment that is stored in a subdirectory somewhere under the standard Web/Topic/attachment level e.g Web/Topic/attachmentdir/subdir/attachment.gif. While such attachments cannot be created via the UI, they can be created manually on the server.

The individual path components are filtered by $Foswiki::cfg{NameFilter}

StaticMethod normalizeFileName( $string ) → $filename

Throws an exception if $string contains filtered characters, as defined by $Foswiki::cfg{NameFilter}

The returned string is not tainted, but it may contain shell metacharacters and even control characters.

DEPRECATED - provided for compatibility only. Do not use! If you want to validate an attachment, use untaint($name, \&validateAttachmentName)

StaticMethod sanitizeAttachmentName($fname) → ($fileName, $origName)

Given a file name received in a query parameter, sanitise it. Returns the sanitised name together with the basename before sanitisation.

Sanitation includes removal of all leading path components, filtering illegal characters and mapping client file names to a subset of legal server file names.

Avoid using this if you can; encoding attachment names this way is badly broken, much better to use point-of-source validation to ensure only valid attachment names are ever uploaded.

StaticMethod sysCommand( $class, $template, %params ) → ( $data, $exit, $stderr )

Invokes the program described by $template and %params, and returns the output of the program and an exit code. STDOUT is returned. STDERR is returned if possible (or is undef if not). $class is ignored, and is only present for compatibility.

The caller has to ensure that the invoked program does not react in a harmful way to the passed arguments. sysCommand merely ensures that the shell does not interpret any of the passed arguments.

$template is a template command-line for the program, which contains typed tokens that are replaced with parameter values passed in the sysCommand call. For example,

    my ( $output, $exit ) = Foswiki::Sandbox->sysCommand(
        $command,
        FILENAME => $filename );

where $command is a template for the command - for example,

/usr/bin/rcs -i -t-none -kb %FILENAME|F%

$template is split at whitespace, and '' strings contained in it are replaced with $params{VAR}. %params values may consist of scalars and array references. Array references are dereferenced and the array elements are inserted. '' can optionally take the form '%VAR|T%', where FLAG is a single character type flag. Permitted type flags are

• U untaint without further checks -- dangerous,
• F normalize as file name,
• N generalized number,
• S simple, short string,
• D RCS format date