HACKING: Add note about unsafe C functions.

Add a section to the HACKING file listing unsafe C library functions
that should not be used.

1 files changed, 48 insertions, 17 deletions

diff --git a/HACKING b/HACKING
index 9d70637a..0680a037 100644
--- a/HACKING
+++ b/HACKING
@@ -6,22 +6,22 @@ The coding style guidelines for Chocolate Doom are designed to keep the
 style of the original source code.  This maintains consistency throughout
 the program, and does not require the original code to be changed. Some
 of these guidelines are stricter than what was done in the original
-source; follow these when writing new code only: there is no need to 
+source; follow these when writing new code only: there is no need to
 change existing code to fit them.
 
-You should set tabs to _display_ as eight spaces, not four.  However, 
+You should set tabs to _display_ as eight spaces, not four.  However,
 _indentation_ should be four spaces.  If possible, do not use tab
 characters at all.  There is a utility called "expand" which will remove
 tab characters.  For the reasoning behind this, see:
 http://www.jwz.org/doc/tabs-vs-spaces.html
 
 Please write code to an 80 column limit so that it fits within a standard
-80 column terminal.
+80 column terminal. Do not leave trailing whitespace at the end of lines.
 
-Functions should be named like this: 'AB_FunctionName'.  The 'AB' prefix 
+Functions should be named like this: 'AB_FunctionName'.  The 'AB' prefix
 denotes the subsystem (AM_ for automap, G_ for game, etc).  If a
 function is static, you can omit the prefix and just name it like
-'FunctionName'.  Functions and global variables should always be made 
+'FunctionName'.  Functions and global variables should always be made
 static if possible.
 
 Put '_t' on the end of types created with typedef.  Type names like this
@@ -37,7 +37,7 @@ Use C++-style comments, ie. '//' comments, not '/* ... */' comments.
 I don't care that this isn't standard ANSI C.
 
 Variables should be named like this: 'my_variable_name', not like this:
-'MyVariableName'.  In pointer variable declarations, place the '*' next 
+'MyVariableName'.  In pointer variable declarations, place the '*' next
 to the variable name, not the type.
 
 When using an if, do, while, or for statement, always use the { } braces
@@ -61,7 +61,7 @@ typedef struct
     char *member2;
 } my_structure_t;
 
-void FunctionName(int argument, int arg2, int arg3, int arg4, int arg5, 
+void FunctionName(int argument, int arg2, int arg3, int arg4, int arg5,
                   int arg6, int arg7)
 {
     if (condition)
@@ -72,7 +72,7 @@ void FunctionName(int argument, int arg2, int arg3, int arg4, int arg5,
     {
         body;
     }
-    else 
+    else
     {
         body;
     }
@@ -88,11 +88,11 @@ void FunctionName(int argument, int arg2, int arg3, int arg4, int arg5,
         case FIRST:
             code;
             break;
-            
+
         case SECOND:
             code;
             break;
-            
+
         default:
             break;
     }
@@ -107,26 +107,57 @@ void FunctionName(int argument, int arg2, int arg3, int arg4, int arg5,
         loop_body;
     }
 
-    do 
+    do
     {
 
     } while (condition);
 }
 
+Security
+========
+
+The C standard library has a number of unsafe functions that should be
+avoided when writing code for Chocolate Doom. These are:
+
+    Unsafe function       Safer alternative
+    ---------------------------------------------
+    gets()                fgets(.., stdin)
+    sprintf               snprintf()
+    strcpy()              M_StringCopy()
+    strncpy()             M_StringCopy()
+    strcat()              M_StringConcat()
+    strncat()             M_StringConcat()
+
+Lots of the code includes calls to DEH_String() to simulate string
+replacement by the Dehacked tool. Be careful when using Dehacked
+replacements of printf format strings. For example, do not do this:
+
+    printf(DEH_String("foo %s"), s);
+    sprintf(mybuf, DEH_String("bar %s"), t);
+
+Instead do this:
+
+    DEH_printf("foo %s", s);
+    DEH_snprintf(mybuf, sizeof(mybuf), "bar %s", t);
+
+This does the format string replacement safely in a way that checks
+the arguments securely.
+
+
 Portability
 ===========
 
 Chocolate Doom is designed to be cross-platform and work on different
 Operating Systems and processors.  Bear this in mind when writing code.
 
-Do not use the long type (its size differs across platforms; use 
+Do not use the long type (its size differs across platforms; use
 int or int64_t depending on which you want).
 
 Use Doom's byte data type for byte data. 'int' is assumed to be a
 32-bit integer, and 'short' is a 16-bit integer. You can also use the
 ISO C99 data types: intN_t and uintN_t where N is 8,16,32,64.
 
-Be careful with platform dependencies: do not use Windows API 
+Be careful with platform dependencies: do not use Windows API
 functions, for example.  Use SDL where possible.
 
 Preprocessor #defines are set that can be used to identify the OS
@@ -134,9 +165,9 @@ if necessary: _WIN32 for Windows and __MACOSX__ for MacOS X. Others
 are set through SDL.  Try to avoid this if possible.
 
 Be careful of endianness!  Doom has SHORT() and LONG() macros that
-do endianness conversion.  Never assume that integer types have a 
-particular byte ordering.  Similarly, never assume that fields 
-inside a structure are aligned in a particular way.  This is most 
+do endianness conversion.  Never assume that integer types have a
+particular byte ordering.  Similarly, never assume that fields
+inside a structure are aligned in a particular way.  This is most
 relevant when reading or writing data to a file or a network pipe.
 
 For signed integers, you shouldn't assume that (i >> n) is the same as
@@ -148,7 +179,7 @@ GNU GPL and licensing
 =====================
 
 All code submitted to the project must be licensed under the GNU GPL or a
-compatible license.  If you use code that you haven't 100% written 
+compatible license.  If you use code that you haven't 100% written
 yourself, say so. Add a copyright header to the start of every file.  Use
 this template: