Credit Mendel.

[pintos-anon] / doc / standards.texi

diff --git a/doc/standards.texi b/doc/standards.texi
index 4b3bbefc4f68dc14b0e84d00167ff8d99fe95a1c..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
 


@@ -65,9 +70,15 @@ There are a few exceptions:
 
 @itemize @bullet
 @item
 
 @itemize @bullet
 @item

-Project 1 has a few parts that we must be able to turn on and off via
-conditional compilation.  You must use the macros we specify for those
-parts.
+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
+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.

 
 @item
 Code written for extra credit may be included conditionally.  If the
 
 @item
 Code written for extra credit may be included conditionally.  If the


@@ -120,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


@@ -134,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


@@ -142,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


@@ -156,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


@@ -166,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