-@node Coding Standards, , Multilevel Feedback Scheduling, Top
+@node Coding Standards, Project Documentation, Multilevel Feedback Scheduling, Top
@appendix Coding Standards
All of you should have taken a class like CS 107, so we expect you to
@menu
* Coding Style::
* Conditional Compilation::
+* C99::
+* Unsafe String Functions::
@end menu
@node Coding Style
Coding Standards}. We encourage you to follow the applicable parts of
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.
+gratuitous differences in style from one function to another. If your
+code is too ugly, it will cost you points.
+
+Please limit C source file lines to at most 79 characters long.
+
+Pintos comments sometimes refer to external 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}).
+
+If you remove existing Pintos code, please delete it from your source
+file entirely. Don't just put it into a comment or a conditional
+compilation directive, because that makes the resulting code hard to
+read. We're only going to do a compile in the directory for the current
+project, so you don't need to make sure that the previous projects also
+compile.
@node Conditional Compilation
@section Conditional Compilation
@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-3, 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-3 Advanced Scheduler}, for
+details.
+
+@item
+Problem 3-2, paging to and from disk. Your page replacement policy must
+default to LRU-like replacement, but we must be able to choose a random
+replacement policy with a compile-time directive. You must use the
+macro name we specify for that part. @xref{Problem 3-2 Paging To and
+From Disk}, for details.
@item
Code written for extra credit may be included conditionally. If the
@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
#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
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
@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
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
-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.
-@item strncpy()
+@item strncpy
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}. Use @func{strlcat} instead.
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.
-Again, use @code{strlcat()}.
+Again, use @func{strlcat}.
-@item strtok()
+@item strtok
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.
-@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.
-@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
projects / pintos-anon / blobdiff