Typos in sqsetcookie. This might explain a few things. :-)
[squirrelmail.git] / functions / global.php
index d7612d1613efe2b9bae8018a6972124868ee93ab..2903511a7e6b7f8d64ec8c244f916bb6b6083593 100644 (file)
@@ -7,7 +7,7 @@
  * It also has some session register functions that work across various
  * php versions.
  *
- * @copyright © 1999-2006 The SquirrelMail Project Team
+ * @copyright © 1999-2007 The SquirrelMail Project Team
  * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  * @version $Id$
  * @package squirrelmail
@@ -93,9 +93,7 @@ function sqsession_register ($var, $name) {
 
     sqsession_is_active();
 
-    $_SESSION["$name"] = $var;
-
-    session_register("$name");
+    $_SESSION[$name] = $var;
 }
 
 /**
@@ -129,6 +127,91 @@ function sqsession_is_registered ($name) {
     return $result;
 }
 
+
+/**
+  * Retrieves a form variable, from a set of possible similarly named
+  * form variables, based on finding a different, single field.  This
+  * is intended to allow more than one same-named inputs in a single
+  * <form>, where the submit button that is clicked tells us which
+  * input we should retrieve.  An example is if we have:
+  *     <select name="startMessage_1">
+  *     <select name="startMessage_2">
+  *     <input type="submit" name="form_submit_1" />
+  *     <input type="submit" name="form_submit_2" />
+  * and we want to know which one of the select inputs should be
+  * returned as $startMessage (without the suffix!), this function
+  * decides by looking for either "form_submit_1" or "form_submit_2"
+  * (both should not appear).  In this example, $name should be
+  * "startMessage" and $indicator_field should be "form_submit".
+  *
+  * NOTE that form widgets must be named with the suffix "_1", "_2", "_3"
+  *      and so on, or this function will not work.
+  *
+  * If more than one of the indicator fields is found, the first one
+  * (numerically) will win.
+  *
+  * If an indicator field is found without a matching input ($name)
+  * field, FALSE is returned.
+  *
+  * If no indicator fields are found, a field of $name *without* any
+  * suffix is searched for (but only if $fallback_no_suffix is TRUE),
+  * and if not found, FALSE is ultimately returned.
+  *
+  * It should also be possible to use the same string for both
+  * $name and $indicator_field to look for the first possible
+  * widget with a suffix that can be found (and possibly fallback
+  * to a widget without a suffix).
+  *
+  * @param string name the name of the var to search
+  * @param mixed value the variable to return
+  * @param string indicator_field the name of the field upon which to base
+  *                               our decision upon (see above)
+  * @param int search constant defining where to look
+  * @param bool fallback_no_suffix whether or not to look for $name with
+  *                                no suffix when nothing else is found
+  * @param mixed default the value to assign to $value when nothing is found
+  * @param int typecast force variable to be cast to given type (please
+  *                     use SQ_TYPE_XXX constants or set to FALSE (default)
+  *                     to leave variable type unmolested)
+  *
+  * @return bool whether variable is found.
+  */
+function sqGetGlobalVarMultiple($name, &$value, $indicator_field,
+                                $search = SQ_INORDER,
+                                $fallback_no_suffix=TRUE, $default=NULL,
+                                $typecast=FALSE) {
+
+    // Set arbitrary max limit -- should be much lower except on the
+    // search results page, if there are many (50 or more?) mailboxes
+    // shown, this may not be high enough.  Is there some way we should
+    // automate this value?
+    //
+    $max_form_search = 100;
+
+    for ($i = 1; $i <= $max_form_search; $i++) {
+        if (sqGetGlobalVar($indicator_field . '_' . $i, $temp, $search)) {
+            return sqGetGlobalVar($name . '_' . $i, $value, $search, $default, $typecast);
+        }
+    }
+
+
+    // no indicator field found; just try without suffix if allowed
+    //
+    if ($fallback_no_suffix) {
+        return sqGetGlobalVar($name, $value, $search, $default, $typecast);
+    }
+
+
+    // no dice, set default and return FALSE
+    //
+    if (!is_null($default)) {
+        $value = $default;
+    }
+    return FALSE;
+
+}
+
+
 /**
  * Search for the var $name in $_SESSION, $_POST, $_GET, $_COOKIE, or $_SERVER
  * and set it in provided var.
@@ -147,9 +230,11 @@ function sqsession_is_registered ($name) {
  * @param string name the name of the var to search
  * @param mixed value the variable to return
  * @param int search constant defining where to look
+ * @param mixed default the value to assign to $value when nothing is found
  * @param int typecast force variable to be cast to given type (please
  *                     use SQ_TYPE_XXX constants or set to FALSE (default)
  *                     to leave variable type unmolested)
+ *
  * @return bool whether variable is found.
  */
 function sqgetGlobalVar($name, &$value, $search = SQ_INORDER, $default = NULL, $typecast = false) {
@@ -209,7 +294,7 @@ function sqgetGlobalVar($name, &$value, $search = SQ_INORDER, $default = NULL, $
             case SQ_TYPE_BOOL: $value = (bool) $value; break;
             default: break;
         }
-    } else if (!is_null($default)) {
+    } else if (!$result && !is_null($default)) {
         $value = $default;
     }
     return $result;
@@ -218,6 +303,13 @@ function sqgetGlobalVar($name, &$value, $search = SQ_INORDER, $default = NULL, $
 /**
  * Deletes an existing session, more advanced than the standard PHP
  * session_destroy(), it explicitly deletes the cookies and global vars.
+ *
+ * WARNING: Older PHP versions have some issues with session management.
+ * See http://bugs.php.net/11643 (warning, spammed bug tracker) and
+ * http://bugs.php.net/13834. SID constant is not destroyed in PHP 4.1.2,
+ * 4.2.3 and maybe other versions. If you restart session after session
+ * is destroyed, affected PHP versions produce PHP notice. Bug should
+ * be fixed only in 4.3.0
  */
 function sqsession_destroy() {
 
@@ -232,11 +324,11 @@ function sqsession_destroy() {
      * merging of sessions.
      */
 
-    global $base_uri;
+    global $base_uri, $_COOKIE, $_SESSION;
 
-    if (isset($_COOKIE[session_name()])) sqsetcookie(session_name(), '', 0, $base_uri);
-    if (isset($_COOKIE['username'])) sqsetcookie('username','',0,$base_uri);
-    if (isset($_COOKIE['key'])) sqsetcookie('key','',0,$base_uri);
+    if (isset($_COOKIE[session_name()]) && session_name()) sqsetcookie(session_name(), '', 0, $base_uri);
+    if (isset($_COOKIE['username']) && $_COOKIE['username']) sqsetcookie('username','',0,$base_uri);
+    if (isset($_COOKIE['key']) && $_COOKIE['key']) sqsetcookie('key','',0,$base_uri);
 
     $sessid = session_id();
     if (!empty( $sessid )) {
@@ -250,30 +342,35 @@ function sqsession_destroy() {
  * start a session up.  php.net doesn't tell you that $_SESSION
  * (even though autoglobal), is not created unless a session is
  * started, unlike $_POST, $_GET and such
+ * Update: (see #1685031) the session ID is left over after the
+ * session is closed in some PHP setups; this function just becomes
+ * a passthru to sqsession_start(), but leaving old code in for
+ * edification.
  */
 function sqsession_is_active() {
-    $sessid = session_id();
-    if ( empty( $sessid ) ) {
+    //$sessid = session_id();
+    //if ( empty( $sessid ) ) {
         sqsession_start();
-    }
+    //}
 }
 
 /**
  * Function to start the session and store the cookie with the session_id as
  * HttpOnly cookie which means that the cookie isn't accessible by javascript
  * (IE6 only)
+ * Note that as sqsession_is_active() no longer discriminates as to when 
+ * it calls this function, session_start() has to have E_NOTICE suppression
+ * (thus the @ sign).
  */
 function sqsession_start() {
     global $base_uri;
 
-    session_start();
+    @session_start();
     $session_id = session_id();
 
     // session_starts sets the sessionid cookie buth without the httponly var
     // setting the cookie again sets the httponly cookie attribute
-
-    // disable, @see sqsetcookie and php 5.1.2
-    // sqsetcookie(session_name(),session_id(),false,$base_uri);
+    sqsetcookie(session_name(),$session_id,false,$base_uri);
 }
 
 
@@ -288,61 +385,39 @@ function sqsession_start() {
  * @param boolean $bHttpOnly Disallow JS to access the cookie (IE6 only)
  * @return void
  */
-function sqsetcookie($sName,$sValue,$iExpire=false,$sPath="",$sDomain="",$bSecure=false,$bHttpOnly=true,$bFlush=false) {
-    static $sCookieCache;
-    if (!isset($sCache)) {
-        $sCache = '';
-    }
-    /**
-     * We have to send all cookies with one header call otherwise we loose cookies.
-     * In order to achieve that the sqsetcookieflush function calls this function with $bFlush = true.
-     * If that happens we send the cookie header.
-     */
-    if ($bFlush) {
-        // header($sCookieCache);
-        return;
+function sqsetcookie($sName,$sValue='deleted',$iExpire=0,$sPath="",$sDomain="",$bSecure=false,$bHttpOnly=true) {
+    // if we have a secure connection then limit the cookies to https only.
+    if ($sName && isset($_SERVER['HTTPS']) && $_SERVER['HTTPS']) {
+        $bSecure = true;
     }
-    if (!$sName) return;
-
-    // php 5.1.2 and 4.4.2 do not allow to send multiple headers at once.
-    // Because that's the only way to get this thing working we fallback to
-    // setcookie until we solved this
-    if ($iExpire===false) $iExpire = 0;
-    setcookie($sName, $sValue, $iExpire, $sPath);
-    return;
-
-    $sHeader = "Set-Cookie: $sName=$sValue";
-    if ($sPath) {
-        $sHeader .= "; path=$sPath";
-    }
-    if ($iExpire !== false) {
-        $sHeader .= "; Max-Age=$iExpire";
-        // php uses Expire header, also add the expire header
-        $sHeader .= "; expires=". gmdate('D, d-M-Y H:i:s T',$iExpire);
-    }
-    if ($sDomain) {
-        $sHeader .= "; Domain=$sDomain";
-    }
-    // TODO: IE for Mac (5.2) thinks that semicolon is part of cookie domain
-    if ($bSecure) {
-        $sHeader .= "; Secure";
-    }
-    if ($bHttpOnly) {
-        $sHeader .= "; HttpOnly";
-    }
-    // $sHeader .= "; Version=1";
-    $sCookieCache .= $sHeader ."\r\n";
-    //header($sHeader."\r\n");
-}
 
-/**
- * Send the cookie header
- *
- * Cookies set with sqsetcookie will bet set after a sqsetcookieflush call.
- * @return void
- */
-function sqsetcookieflush() {
-    sqsetcookie('','','','','','','',true);
+    // admin config can override the restriction of secure-only cookies
+    global $only_secure_cookies;
+    if (!$only_secure_cookies)
+        $bSecure = false;
+
+    if (false && check_php_version(5,2)) {
+       // php 5 supports the httponly attribute in setcookie, but because setcookie seems a bit
+       // broken we use the header function for php 5.2 as well. We might change that later.
+       //setcookie($sName,$sValue,(int) $iExpire,$sPath,$sDomain,$bSecure,$bHttpOnly);
+    } else {
+        if (!empty($sDomain)) {
+            // Fix the domain to accept domains with and without 'www.'.
+            if (strtolower(substr($sDomain, 0, 4)) == 'www.')  $sDomain = substr($sDomain, 4);
+            $sDomain = '.' . $sDomain;
+
+            // Remove port information.
+            $Port = strpos($sDomain, ':');
+            if ($Port !== false)  $sDomain = substr($sDomain, 0, $Port);
+        }
+        if (!$sValue) $sValue = 'deleted';
+        header('Set-Cookie: ' . rawurlencode($sName) . '=' . rawurlencode($sValue)
+                            . (empty($iExpire) ? '' : '; expires=' . gmdate('D, d-M-Y H:i:s', $iExpire) . ' GMT')
+                            . (empty($sPath) ? '' : '; path=' . $sPath)
+                            . (empty($sDomain) ? '' : '; domain=' . $sDomain)
+                            . (!$bSecure ? '' : '; secure')
+                            . (!$bHttpOnly ? '' : '; HttpOnly'), false);
+    }
 }
 
 /**
@@ -422,3 +497,502 @@ function php_self () {
 
     return '';
 }
+
+
+/**
+  * Find files and/or directories in a given directory optionally
+  * limited to only those with the given file extension.  If the
+  * directory is not found or cannot be opened, no error is generated;
+  * only an empty file list is returned.
+FIXME: do we WANT to throw an error or a notice or... or return FALSE?
+  *
+  * @param string $directory_path         The path (relative or absolute)
+  *                                       to the desired directory.
+  * @param mixed  $extension              The file extension filter - either
+  *                                       an array of desired extension(s),
+  *                                       or a comma-separated list of same
+  *                                       (optional; default is to return 
+  *                                       all files (dirs).
+  * @param boolean $return_filenames_only When TRUE, only file/dir names
+  *                                       are returned, otherwise the
+  *                                       $directory_path string is
+  *                                       prepended to each file/dir in
+  *                                       the returned list (optional;
+  *                                       default is filename/dirname only)
+  * @param boolean $include_directories   When TRUE, directories are
+  *                                       included (optional; default
+  *                                       DO include directories).
+  * @param boolean $directories_only      When TRUE, ONLY directories
+  *                                       are included (optional; default
+  *                                       is to include files too).
+  * @param boolean $separate_files_and_directories When TRUE, files and
+  *                                                directories are returned
+  *                                                in separate lists, so
+  *                                                the return value is
+  *                                                formatted as a two-element
+  *                                                array with the two keys
+  *                                                "FILES" and "DIRECTORIES",
+  *                                                where corresponding values
+  *                                                are lists of either all
+  *                                                files or all directories
+  *                                                (optional; default do not
+  *                                                split up return array).
+  * @param boolean $only_sm               When TRUE, a security check will
+  *                                       limit directory access to only
+  *                                       paths within the SquirrelMail 
+  *                                       installation currently being used
+  *                                       (optional; default TRUE)
+  *
+  * @return array The requested file/directory list(s).
+  *
+  * @since 1.5.2
+  *
+  */
+function list_files($directory_path, $extensions='', $return_filenames_only=TRUE,
+                    $include_directories=TRUE, $directories_only=FALSE,
+                    $separate_files_and_directories=FALSE, $only_sm=TRUE) {
+
+    $files = array();
+    $directories = array();
+
+
+    // make sure requested path is under SM_PATH if needed
+    //
+    if ($only_sm) {
+        if (strpos(realpath($directory_path), realpath(SM_PATH)) !== 0) {
+            //plain_error_message(_("Illegal filesystem access was requested"));
+            echo _("Illegal filesystem access was requested");
+            exit;
+        }
+    }
+
+
+    // validate given directory
+    //
+    if (empty($directory_path)
+     || !is_dir($directory_path)
+     || !($DIR = opendir($directory_path))) {
+        return $files;
+    }
+
+
+    // ensure extensions is an array and is properly formatted 
+    //
+    if (!empty($extensions)) {
+        if (!is_array($extensions))
+            $extensions = explode(',', $extensions);
+        $temp_extensions = array();
+        foreach ($extensions as $ext)
+            $temp_extensions[] = '.' . trim(trim($ext), '.');
+        $extensions = $temp_extensions;
+    } else $extensions = array();
+
+
+    $directory_path = rtrim($directory_path, '/');
+
+
+    // parse through the files
+    //
+    while (($file = readdir($DIR)) !== false) {
+
+        if ($file == '.' || $file == '..') continue;
+
+        if (!empty($extensions))
+            foreach ($extensions as $ext)
+                if (strrpos($file, $ext) !== (strlen($file) - strlen($ext)))
+                    continue 2;
+
+        // only use is_dir() if we really need to (be as efficient as possible)
+        //
+        $is_dir = FALSE;
+        if (!$include_directories || $directories_only
+                                  || $separate_files_and_directories) {
+            if (is_dir($directory_path . '/' . $file)) {
+                if (!$include_directories) continue;
+                $is_dir = TRUE;
+                $directories[] = ($return_filenames_only
+                               ? $file
+                               : $directory_path . '/' . $file);
+            }
+            if ($directories_only) continue;
+        }
+
+        if (!$separate_files_and_directories
+         || ($separate_files_and_directories && !$is_dir)) {
+            $files[] = ($return_filenames_only
+                     ? $file
+                     : $directory_path . '/' . $file);
+        }
+
+    }
+    closedir($DIR);
+
+
+    if ($directories_only) return $directories;
+    if ($separate_files_and_directories) return array('FILES' => $files,
+                                                      'DIRECTORIES' => $directories);
+    return $files;
+
+}
+
+
+/**
+ * Print variable
+ *
+ * sm_print_r($some_variable, [$some_other_variable [, ...]]);
+ *
+ * Debugging function - does the same as print_r, but makes sure special
+ * characters are converted to htmlentities first.  This will allow
+ * values like <some@email.address> to be displayed.
+ * The output is wrapped in <<pre>> and <</pre>> tags.
+ * Since 1.4.2 accepts unlimited number of arguments.
+ * @since 1.4.1
+ * @return void
+ */
+function sm_print_r() {
+    ob_start();  // Buffer output
+    foreach(func_get_args() as $var) {
+        print_r($var);
+        echo "\n";
+        // php has get_class_methods function that can print class methods
+        if (is_object($var)) {
+            // get class methods if $var is object
+            $aMethods=get_class_methods(get_class($var));
+            // make sure that $aMethods is array and array is not empty
+            if (is_array($aMethods) && $aMethods!=array()) {
+                echo "Object methods:\n";
+                foreach($aMethods as $method) {
+                    echo '* ' . $method . "\n";
+                }
+            }
+            echo "\n";
+        }
+    }
+    $buffer = ob_get_contents(); // Grab the print_r output
+    ob_end_clean();  // Silently discard the output & stop buffering
+    print '<div align="left"><pre>';
+    print htmlentities($buffer);
+    print '</pre></div>';
+}
+
+
+/**
+  * SquirrelMail wrapper for popen()/proc_open()
+  *
+  * This emulates popen() by using proc_open() if at all
+  * possible (reverts seamlessly to popen() if proc_open()
+  * is not supported in current PHP installation).
+  * 
+  * This is intended for use with the related sq_pclose(),
+  * sq_get_pipe_stdout() and sq_get_pipe_stderr() functions, 
+  * the latter of which add an easy interface for retrieving 
+  * output from a child process that was opened with traditional
+  * popen() syntax (in write mode), while not breaking under
+  * earlier versions of PHP.
+  *
+  * @param string $command The command identifying what to 
+  *                        execute in the child process.
+  * @param string $mode    The desired mode for the 
+  *                        unidirectional pipe that is returned;
+  *                        either 'r' for read or 'w' for write.
+  *
+  * @return resource A handle on the desired read or write pipe
+  *                  to the child process, or FALSE if the 
+  *                  process cannot be created.
+  *
+  * @since 1.5.2
+  *
+  */
+function sq_popen($command, $mode) {
+
+    $mode = strtolower($mode{0});
+
+
+    if (!function_exists('proc_open'))
+        return popen($command, $mode);
+
+
+    // set up our process store if not done already
+    //
+    global $processes;
+    if (empty($processes))
+        $processes = array();
+
+
+    // define read, write and error pipes
+    //
+    $descriptors = array(0 => array('pipe', 'r'),
+                         1 => array('pipe', 'w'),
+                         2 => array('pipe', 'w'));
+
+
+    // start the child process
+    //
+    $proc = proc_open($command, $descriptors, $pipes);
+    if (!is_resource($proc))
+        return FALSE;
+
+
+    // when in read mode, we'll return a handle to the child's write pipe
+    //
+    if ($mode == 'r')
+        $return_value = $pipes[1];
+    else if ($mode == 'w')
+        $return_value = $pipes[0];
+    else
+        die('sq_popen() expects $mode to be "r" or "w"');
+
+
+    // store the handle to the process and its pipes
+    // internally, keyed by whatever handle we'll be
+    // returning
+    //
+    $processes[$return_value] = array($proc, $pipes);
+
+
+    return $return_value;
+
+}
+
+
+/**
+  * Get STDERR output from a child process
+  * 
+  * This is designed to be used with processes that were
+  * opened with sq_popen(), and will return any output 
+  * that may be available from STDERR of the child process
+  * at the current time.
+  * 
+  * If a value is given for $timeout_seconds, this function
+  * will wait that long for output in case there is none
+  * right now.
+  *
+  * In PHP environments that do not support proc_open(),
+  * an empty string will always be returned.
+  *
+  * @param resource $handle     The handle to the child process,
+  *                             as returned from sq_popen().
+  * @param int $timeout_seconds The number of seconds to wait
+  *                             for output if there is none 
+  *                             available immediately (OPTIONAL;
+  *                             default is not to wait)
+  * @param boolean $quiet       When TRUE, errors are silently
+  *                             ignored (OPTIONAL; default is TRUE).
+  *                                       
+  * @return string Any STDERR output that may have been found.
+  * 
+  * @since 1.5.2
+  *
+  */
+function sq_get_pipe_stderr($handle, $timeout_seconds=0, $quiet=TRUE) {
+
+    // yes, we are testing for proc_OPEN
+    // because we need to know how the
+    // handle was actually OPENED
+    //
+    if (!function_exists('proc_open'))
+        return '';
+
+
+    // get our process out of the process store
+    //
+    global $processes;
+    if (!is_array($processes) || !isset($processes[$handle])) {
+        if (!quiet) {
+            plain_error_message(_("Failed to find corresponding open process handle"));
+        }
+        return '';
+    }
+    $proc = $processes[$handle];
+
+
+    // get all we can from stderr, don't wait longer
+    // than our timeout for input
+    //
+    $contents = '';
+    $read = array($proc[1][2]);
+    $write = NULL;
+    $except = NULL;
+    if (stream_select($read, $write, $except, $timeout_seconds))
+        while (!feof($proc[1][2])) $contents .= fread($proc[1][2], 8192);
+    return $contents;
+
+}
+
+
+/**
+  * Get STDOUT output from a child process
+  * 
+  * This is designed to be used with processes that were
+  * opened with sq_popen(), and will return any output 
+  * that may be available from STDOUT of the child process
+  * at the current time.
+  * 
+  * If a value is given for $timeout_seconds, this function
+  * will wait that long for output in case there is none
+  * right now.
+  *
+  * In PHP environments that do not support proc_open(),
+  * an empty string will always be returned.
+  *
+  * @param resource $handle     The handle to the child process,
+  *                             as returned from sq_popen().
+  * @param int $timeout_seconds The number of seconds to wait
+  *                             for output if there is none 
+  *                             available immediately (OPTIONAL;
+  *                             default is not to wait)
+  * @param boolean $quiet       When TRUE, errors are silently
+  *                             ignored (OPTIONAL; default is TRUE).
+  *                                       
+  * @return string Any STDOUT output that may have been found.
+  * 
+  * @since 1.5.2
+  *
+  */
+function sq_get_pipe_stdout($handle, $timeout_seconds=0, $quiet=TRUE) {
+
+    // yes, we are testing for proc_OPEN
+    // because we need to know how the
+    // handle was actually OPENED
+    //
+    if (!function_exists('proc_open'))
+        return '';
+
+
+    // get our process out of the process store
+    //
+    global $processes;
+    if (!is_array($processes) || !isset($processes[$handle])) {
+        if (!quiet) {
+            plain_error_message(_("Failed to find corresponding open process handle"));
+        }
+        return '';
+    }
+    $proc = $processes[$handle];
+
+
+    // get all we can from stdout, don't wait longer
+    // than our timeout for input
+    //
+    $contents = '';
+    $read = array($proc[1][1]);
+    $write = NULL;
+    $except = NULL;
+    if (stream_select($read, $write, $except, $timeout_seconds))
+       while (!feof($proc[1][1])) $contents .= fread($proc[1][1], 8192);
+    return $contents;
+
+}
+
+
+/**
+  * SquirrelMail wrapper for pclose()/proc_close()
+  * 
+  * This is designed to be used with processes that were
+  * opened with sq_popen(), and will correctly close 
+  * all pipes/handles that were opened as well as the 
+  * child process itself.
+  *
+  * @param resource $handle     The handle to the child process,
+  *                             as returned from sq_popen().
+  * @param boolean $quiet       When TRUE, errors are silently
+  *                             ignored (OPTIONAL; default is TRUE).
+  *                                       
+  * @return int The termination status of the child process.
+  * 
+  * @since 1.5.2
+  *
+  */
+function sq_pclose($handle, $quiet=TRUE) {
+
+    // yes, we are testing for proc_OPEN
+    // because we need to know how the
+    // handle was actually OPENED
+    //
+    if (!function_exists('proc_open'))
+        return pclose($handle);
+
+
+    // get our process out of the process store
+    //
+    global $processes;
+    if (!is_array($processes) || !isset($processes[$handle])) {
+        if (!quiet) {
+            plain_error_message(_("Failed to find corresponding open process handle"));
+        }
+        return 127;
+    }
+    $proc = $processes[$handle];
+    unset($processes[$handle]);
+
+
+    // close all pipes
+    //
+    fclose($proc[1][0]);
+    fclose($proc[1][1]);
+    fclose($proc[1][2]);
+
+
+    // close process
+    //
+    return proc_close($proc[0]);
+
+}
+
+
+/**
+  * Sanitize a value using htmlspecialchars() or similar, but also
+  * recursively run htmlspecialchars() (or similar) on array keys
+  * and values.
+  *
+  * If $value is not a string or an array with strings in it,
+  * the value is returned as is.
+  *
+  * @param mixed $value       The value to be sanitized.
+  * @param mixed $quote_style Either boolean or an integer.  If it
+  *                           is an integer, it must be the PHP
+  *                           constant indicating if/how to escape
+  *                           quotes: ENT_QUOTES, ENT_COMPAT, or
+  *                           ENT_NOQUOTES.  If it is a boolean value,
+  *                           it must be TRUE and thus indicates
+  *                           that the only sanitizing to be done
+  *                           herein is to replace single and double
+  *                           quotes with &#039; and &quot;, no other
+  *                           changes are made to $value.  If it is
+  *                           boolean and FALSE, behavior reverts
+  *                           to same as if the value was ENT_QUOTES
+  *                           (OPTIONAL; default is ENT_QUOTES).
+  *
+  * @return mixed The sanitized value.
+  *
+  * @since 1.5.2
+  *
+  **/
+function sq_htmlspecialchars($value, $quote_style=ENT_QUOTES) {
+
+    if ($quote_style === FALSE) $quote_style = ENT_QUOTES;
+
+    // array?  go recursive...
+    //
+    if (is_array($value)) {
+        $return_array = array();
+        foreach ($value as $key => $val) {
+            $return_array[sq_htmlspecialchars($key, $quote_style)]
+                = sq_htmlspecialchars($val, $quote_style);
+        }
+        return $return_array;
+
+    // sanitize strings only
+    //
+    } else if (is_string($value)) {
+        if ($quote_style === TRUE)
+            return str_replace(array('\'', '"'), array('&#039;', '&quot;'), $value);
+        else
+            return htmlspecialchars($value, $quote_style);
+    }
+
+    // anything else gets returned with no changes
+    //
+    return $value;
+
+}