[Secure Coding] master: C: Add material on global variables (fa41f38)

[fweimer at fedoraproject.org]

Repository : http://git.fedorahosted.org/git/?p=secure-coding.git

On branch  : master

>---------------------------------------------------------------

commit fa41f38b864810921f947e08904a299928e80223
Author: Florian Weimer <fweimer at redhat.com>
Date:   Mon Aug 26 16:15:53 2013 +0200

    C: Add material on global variables


>---------------------------------------------------------------

 defensive-coding/en-US/C-Language.xml              |   46 ++++++++++++++++++++
 ...ntials-Close.xml => C-Globals-String_Array.xml} |    7 +++-
 defensive-coding/src/C-Globals.c                   |   17 +++++++
 defensive-coding/src/src.mk                        |    1 +
 4 files changed, 70 insertions(+), 1 deletions(-)

diff --git a/defensive-coding/en-US/C-Language.xml b/defensive-coding/en-US/C-Language.xml
index 83f6da0..b039ed2 100644
--- a/defensive-coding/en-US/C-Language.xml
+++ b/defensive-coding/en-US/C-Language.xml
@@ -147,4 +147,50 @@
       integer overflow.
     </para>
   </section>
+
+  <section id="sect-Defensive_Coding-C-Globals">
+    <title>Global variables</title>
+    <para>
+      Global variables should be avoided because they usually lead to
+      thread safety hazards.  In any case, they should be declared
+      <literal>static</literal>, so that access is restricted to a
+      single translation unit.
+    </para>
+    <para>
+      Global constants are not a problem, but declaring them can be
+      tricky.  <xref linkend="ex-Defensive_Coding-C-Globals-String_Array"/>
+      shows how to declare a constant array of constant strings.
+      The second <literal>const</literal> is needed to make the
+      array constant, and not just the strings.  It must be placed
+      after the <literal>*</literal>, and not before it.
+    </para>
+    <example id="ex-Defensive_Coding-C-Globals-String_Array">
+      <title>Declaring a constant array of constant strings</title>
+      <xi:include href="snippets/C-Globals-String_Array.xml"
+		  xmlns:xi="http://www.w3.org/2001/XInclude" />
+    </example>
+    <para>
+      Sometimes, static variables local to functions are used as a
+      replacement for proper memory management.  Unlike non-static
+      local variables, it is possible to return a pointer to static
+      local variables to the caller.  But such variables are
+      well-hidden, but effectively global (just as static variables at
+      file scope). It is difficult to add thread safety afterwards if
+      such interfaces are used.  Merely dropping the
+      <literal>static</literal> keyword in such cases leads to
+      undefined behavior.
+    </para>
+    <para>
+      Another source for static local variables is a desire to reduce
+      stack space usage on embedded platforms, where the stack may
+      span only a few hundred bytes.  If this is the only reason why
+      the <literal>static</literal> keyword is used, it can just be
+      dropped, unless the object is very large (larger than
+      128 kilobytes on 32 bit platforms).  In the latter case, it is
+      recommended to allocate the object using
+      <literal>malloc</literal>, to obtain proper array checking, for
+      the same reasons outlined in <xref
+      linkend="sect-Defensive_Coding-C-Allocators-alloca"/>.
+    </para>
+  </section>
 </section>
diff --git a/defensive-coding/en-US/snippets/Features-TLS-GNUTLS-Credentials-Close.xml b/defensive-coding/en-US/snippets/C-Globals-String_Array.xml
similarity index 75%
copy from defensive-coding/en-US/snippets/Features-TLS-GNUTLS-Credentials-Close.xml
copy to defensive-coding/en-US/snippets/C-Globals-String_Array.xml
index 8c28b0f..2f05b7d 100644
--- a/defensive-coding/en-US/snippets/Features-TLS-GNUTLS-Credentials-Close.xml
+++ b/defensive-coding/en-US/snippets/C-Globals-String_Array.xml
@@ -3,5 +3,10 @@
 ]>
 <!-- Automatically generated file.  Do not edit. -->
 <programlisting language="C">
-gnutls_certificate_free_credentials(cred);
+static const char *const string_list[] = {
+  "first",
+  "second",
+  "third",
+  NULL
+};
 </programlisting>
diff --git a/defensive-coding/src/C-Globals.c b/defensive-coding/src/C-Globals.c
new file mode 100644
index 0000000..75b33b4
--- /dev/null
+++ b/defensive-coding/src/C-Globals.c
@@ -0,0 +1,17 @@
+#include <stddef.h>
+
+//+ C Globals-String_Array
+static const char *const string_list[] = {
+  "first",
+  "second",
+  "third",
+  NULL
+};
+//-
+
+// Silence compiler warning
+const char *const *
+get_string_list()
+{
+  return string_list;
+}
diff --git a/defensive-coding/src/src.mk b/defensive-coding/src/src.mk
index 219e70b..d47fc09 100644
--- a/defensive-coding/src/src.mk
+++ b/defensive-coding/src/src.mk
@@ -12,6 +12,7 @@ LDFLAGS = -g
 compile_only += C-Pointers-remaining
 compile_only += C-Arithmetic-add
 compile_only += C-Arithmetic-mult
+compile_only += C-Globals
 
 compile_only += Java-JNI-Pointers
 CFLAGS_Java-JNI-Pointers = \