From 6e9edc1379f2ee97a7fa42cabd4dd7c56241d21e Mon Sep 17 00:00:00 2001
From: Dries Buytaert <dries@buytaert.net>
Date: Sun, 18 Oct 2009 18:36:24 +0000
Subject: [PATCH] - Patch #594518 by jhodgdon: better documentation for
 file_munge_filename().

---
 includes/file.inc | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/includes/file.inc b/includes/file.inc
index 719d046779a..bf4996567bb 100644
--- a/includes/file.inc
+++ b/includes/file.inc
@@ -797,18 +797,24 @@ function file_unmanaged_move($source, $destination = NULL, $replace = FILE_EXIST
 }
 
 /**
- * Munge the filename as needed for security purposes.
+ * Modify a filename as needed for security purposes.
  *
- * For instance the file name "exploit.php.pps" would become "exploit.php_.pps".
+ * Dangerous file names will be altered; for instance, the file name
+ * "exploit.php.pps" will become "exploit.php_.pps". All extensions that are
+ * between 2 and 5 characters in length, internal to the file name, and not
+ * included in $extensions will be altered by adding an underscore. If variable
+ * 'allow_insecure_uploads' evaluates to TRUE, no alterations will be made.
  *
  * @param $filename
- *   The name of a file to modify.
+ *   File name to modify.
  * @param $extensions
- *   A space separated list of extensions that should not be altered.
+ *   A space-separated list of extensions that should not be altered.
  * @param $alerts
- *   Whether alerts (watchdog, drupal_set_message()) should be displayed.
+ *   If TRUE, drupal_set_message() will be called to display a message if the
+ *   file name was changed.
+ *
  * @return
- *   $filename The potentially modified $filename.
+ *   The potentially modified $filename.
  */
 function file_munge_filename($filename, $extensions, $alerts = TRUE) {
   $original = $filename;