X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;ds=sidebyside;f=doc%2Fstandards.texi;h=2582e5c58f26e335a2cf4ff9caee5880fa7036da;hb=3cebac2006571a93ea0cbf992faa5eec3454d570;hp=4b3bbefc4f68dc14b0e84d00167ff8d99fe95a1c;hpb=699944803572c46c550a39027c0ebd935b0d61bc;p=pintos-anon diff --git a/doc/standards.texi b/doc/standards.texi index 4b3bbef..2582e5c 100644 --- a/doc/standards.texi +++ b/doc/standards.texi @@ -39,7 +39,20 @@ 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. + +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 @@ -65,9 +78,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-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 +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 @@ -120,7 +141,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 @@ -134,7 +155,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 @@ -142,7 +163,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 @@ -156,6 +177,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 @@ -166,37 +190,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