X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fstandards.texi;h=162ec44ecfde7f06cb4dacd851b991b39dd88c89;hb=59385cfe7f0fc5a66dfc1da7c2e5b817edbcae65;hp=e7ed5686265f8bd94e89b496b7414f6192c631c3;hpb=a3f360bff01c33a4c9167c35f30b760b3a5de8d5;p=pintos-anon diff --git a/doc/standards.texi b/doc/standards.texi index e7ed568..162ec44 100644 --- a/doc/standards.texi +++ b/doc/standards.texi @@ -39,53 +39,31 @@ 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. - -@node Conditional Compilation -@section Conditional Compilation - -Given the scope and complexity of your assignments this quarter, you -may find it convenient while coding and debugging (and we will find it -convenient while grading) to be able to independently turn different -parts of the assignments on and off. To do this, choose a macro name -and use it in conditional -compilation directives, e.g.: - -@example -#ifdef @var{NAME} -@dots{}your code@dots{} -#endif -@end example - -In general, the code that you turn in must not depend on conditional -compilation directives. Project code should be written so that all of -the subproblems for the project function together, and it should -compile properly without the need for any new macros to be defined. -There are a few exceptions: - -@itemize @bullet -@item -Problem 1-2, @code{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 -extra credit code changes the normally expected functionality of the -code, then it @emph{must} be included conditionally, and it must not -be enabled by default. -@end itemize - -You can use @file{constants.h} in @file{pintos/src} to define macros -for conditional compilation. We will replace the @file{constants.h} -that you supply with one of our own when we test your code, so do not -define anything important in it. +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. + +Project code should be written so that all of the subproblems for the +project function together, that is, without the need to rebuild with +different macros defined, etc. If you do extra credit work that +changes normal Pintos behavior so as to interfere with grading, then +you must implement it so that it only acts that way when given a +special command-line option of the form @option{-o @var{name}}, where +@var{name} is a name of your choice. You can add such an option by +modifying @func{argv_init} in @file{threads/init.c}. @node C99 @section C99 @@ -126,7 +104,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 @@ -148,7 +126,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 @@ -162,6 +140,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 @@ -172,37 +153,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