X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fstandards.texi;h=a1c70a47961a69baac2f0bfe906c15870c88677d;hb=2cfc156c39840ce7f1cda6b473de1322691a8a0b;hp=28bfc81f12979d93a542ead5b6662493e7874993;hpb=98c2fc1ab7d395bb92cf4a57233fe432539d26a9;p=pintos-anon diff --git a/doc/standards.texi b/doc/standards.texi index 28bfc81..a1c70a4 100644 --- a/doc/standards.texi +++ b/doc/standards.texi @@ -1,4 +1,4 @@ -@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 @@ -21,6 +21,8 @@ our coding standards will affect our grading. @menu * Coding Style:: * Conditional Compilation:: +* C99:: +* Unsafe String Functions:: @end menu @node Coding Style @@ -37,7 +39,22 @@ follows the @uref{http://www.gnu.org/prep/standards_toc.html, , GNU 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 @@ -63,9 +80,17 @@ There are a few exceptions: @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 @@ -118,7 +143,7 @@ macro giving its maximum value. @item @file{} 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{}, it provides macros @code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of @@ -132,7 +157,7 @@ the C compiler concatenates adjacent string literals: #include @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 @@ -140,7 +165,7 @@ above, you supply it yourself and follow it by any flags, field widths, etc. @item -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 @@ -154,6 +179,9 @@ For @code{size_t} (e.g.@: @samp{%zu}). @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 @@ -164,37 +192,37 @@ A few of the string functions declared in the standard 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