Credit Mendel.

[pintos-anon] / doc / standards.texi

diff --git a/doc/standards.texi b/doc/standards.texi
index 1434a635ecdae320d66bd1a56ed9a977c2438e8c..7af266e9c10b9cecb5be44f8ae190acf9a8048ef 100644 (file)
--- a/doc/standards.texi
+++ b/doc/standards.texi
@@ -41,6 +41,11 @@ them too, especially chapter 5, ``Making the Best Use of C.''  Using a
 different style won't cause actual problems, but it's ugly to see
 gratuitous differences in style from one function to another.
 
 different style won't cause actual problems, but it's ugly to see
 gratuitous differences in style from one function to another.
 

+Pintos comments sometimes refer to outside standards or
+specifications by writing a name inside square brackets, like this:
+@code{[IA32-v3]}.  These names refer to the reference names used in
+this documentation (@pxref{References}).
+

 @node Conditional Compilation
 @section Conditional Compilation
 
 @node Conditional Compilation
 @section Conditional Compilation
 


@@ -64,9 +69,14 @@ compile properly without the need for any new macros to be defined.
 There are a few exceptions:
 
 @itemize @bullet
 There are a few exceptions:
 
 @itemize @bullet

+@item
+Problem 1-2, @func{thread_join}.  Some other code expects
+@code{THREAD_JOIN_IMPLEMENTED} to be defined once you've implemented
+this function.
+

 @item
 Problem 1-4, the advanced scheduler.  We must be able to turn this on
 @item
 Problem 1-4, the advanced scheduler.  We must be able to turn this on

-and off with a compile time directive.  You must use the macro name we
+and off with a compile-time directive.  You must use the macro name we

 specify for that part.  @xref{Problem 1-4 Advanced Scheduler}, for
 details.
 
 specify for that part.  @xref{Problem 1-4 Advanced Scheduler}, for
 details.
 


@@ -121,7 +131,7 @@ macro giving its maximum value.
 
 @item <inttypes.h>
 @file{<stdint.h>} is useful on its own, but it provides no way to pass
 
 @item <inttypes.h>
 @file{<stdint.h>} is useful on its own, but it provides no way to pass

-the types it defines to @code{printf()} and related functions.  This
+the types it defines to @func{printf} and related functions.  This

 header provides macros to help with that.  For every
 @code{int@var{n}_t} defined by @file{<stdint.h>}, it provides macros
 @code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of
 header provides macros to help with that.  For every
 @code{int@var{n}_t} defined by @file{<stdint.h>}, it provides macros
 @code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of


@@ -135,7 +145,7 @@ the C compiler concatenates adjacent string literals:
 #include <inttypes.h>
 @dots{}
 int32_t value = @dots{};
 #include <inttypes.h>
 @dots{}
 int32_t value = @dots{};

-printf ("value=%08"PRId32"\n");
+printf ("value=%08"PRId32"\n", value);

 @end example
 @noindent
 The @samp{%} is not supplied by the @code{PRI} macros.  As shown
 @end example
 @noindent
 The @samp{%} is not supplied by the @code{PRI} macros.  As shown


@@ -143,7 +153,7 @@ above, you supply it yourself and follow it by any flags, field
 widths, etc.
 
 @item <stdio.h>
 widths, etc.
 
 @item <stdio.h>

-The @file{printf()} function has some new type modifiers for printing
+The @func{printf} function has some new type modifiers for printing

 standard types:
 
 @table @samp
 standard types:
 
 @table @samp


@@ -157,6 +167,9 @@ For @code{size_t} (e.g.@: @samp{%zu}).
 @item t
 For @code{ptrdiff_t} (e.g.@: @samp{%td}).
 @end table
 @item t
 For @code{ptrdiff_t} (e.g.@: @samp{%td}).
 @end table

+
+Pintos @func{printf} also implements a nonstandard @samp{'} flag that
+group large numbers with commas to make them easier to read.

 @end table
 
 @node Unsafe String Functions
 @end table
 
 @node Unsafe String Functions


@@ -167,37 +180,37 @@ A few of the string functions declared in the standard
 The worst offenders are intentionally not included in the Pintos C
 library:
 
 The worst offenders are intentionally not included in the Pintos C
 library:
 

-@table @code
-@item strcpy()
+@table @func
+@item strcpy

 When used carelessly this function can overflow the buffer reserved
 When used carelessly this function can overflow the buffer reserved

-for its output string.  Use @code{strlcpy()} instead.  Refer to
+for its output string.  Use @func{strlcpy} instead.  Refer to

 comments in its source code in @code{lib/string.c} for documentation.
 
 comments in its source code in @code{lib/string.c} for documentation.
 

-@item strncpy()
+@item strncpy

 This function can leave its destination buffer without a null string
 terminator and it has performance problems besides.  Again, use
 This function can leave its destination buffer without a null string
 terminator and it has performance problems besides.  Again, use

-@code{strlcpy()}.
+@func{strlcpy}.

 
 

-@item strcat()
-Same issue as @code{strcpy()}, but substitute @code{strlcat()}.
+@item strcat
+Same issue as @func{strcpy}, but substitute @func{strlcat}.

 Again, refer to comments in its source code in @code{lib/string.c} for
 documentation.
 
 Again, refer to comments in its source code in @code{lib/string.c} for
 documentation.
 

-@item strncat()
+@item strncat

 The meaning of its buffer size argument often leads to problems.
 The meaning of its buffer size argument often leads to problems.

-Again, use @code{strlcat()}.
+Again, use @func{strlcat}.

 
 

-@item strtok()
+@item strtok

 Uses global data, so it is unsafe in threaded programs such as
 Uses global data, so it is unsafe in threaded programs such as

-kernels.  Use @code{strtok_r()} instead, and see its source code in
+kernels.  Use @func{strtok_r} instead, and see its source code in

 @code{lib/string.c} for documentation and an example.
 
 @code{lib/string.c} for documentation and an example.
 

-@item sprintf()
-Same issue as @code{strcpy()}.  Use @code{snprintf()} instead.  Refer
+@item sprintf
+Same issue as @func{strcpy}.  Use @func{snprintf} instead.  Refer

 to comments in @code{lib/stdio.h} for documentation.
 
 to comments in @code{lib/stdio.h} for documentation.
 

-@item vsprintf()
-Same issue as @code{strcpy()}.  Use @code{vsnprintf()} instead.
+@item vsprintf
+Same issue as @func{strcpy}.  Use @func{vsnprintf} instead.

 @end table
 
 If you try to use any of these functions, you should get a hint from
 @end table
 
 If you try to use any of these functions, you should get a hint from