2 @appendix Coding Standards
4 @localcodingstandards{}
6 Our standards for coding are most important for grading. We want to
7 stress that aside from the fact that we are explicitly basing part of
8 your grade on these things, good coding practices will improve the
9 quality of your code. This makes it easier for your partners to
10 interact with it, and ultimately, will improve your chances of having a
11 good working program. That said once, the rest of this document will
12 discuss only the ways in which our coding standards will affect our
18 * Unsafe String Functions::
24 Style, for the purposes of our grading, refers to how readable your
25 code is. At minimum, this means that your code is well formatted, your
26 variable names are descriptive and your functions are decomposed and
27 well commented. Any other factors which make it hard (or easy) for us
28 to read or use your code will be reflected in your style grade.
30 The existing Pintos code is written in the GNU style and largely
31 follows the @uref{http://www.gnu.org/prep/standards_toc.html, , GNU
32 Coding Standards}. We encourage you to follow the applicable parts of
33 them too, especially chapter 5, ``Making the Best Use of C.'' Using a
34 different style won't cause actual problems, but it's ugly to see
35 gratuitous differences in style from one function to another. If your
36 code is too ugly, it will cost you points.
38 Please limit C source file lines to at most 79 characters long.
40 Pintos comments sometimes refer to external standards or
41 specifications by writing a name inside square brackets, like this:
42 @code{[IA32-v3a]}. These names refer to the reference names used in
43 this documentation (@pxref{Bibliography}).
45 If you remove existing Pintos code, please delete it from your source
46 file entirely. Don't just put it into a comment or a conditional
47 compilation directive, because that makes the resulting code hard to
50 We're only going to do a compile in the directory for the project being
51 submitted. You don't need to make sure that the previous projects also
54 Project code should be written so that all of the subproblems for the
55 project function together, that is, without the need to rebuild with
56 different macros defined, etc. If you do extra credit work that
57 changes normal Pintos behavior so as to interfere with grading, then
58 you must implement it so that it only acts that way when given a
59 special command-line option of the form @option{-@var{name}}, where
60 @var{name} is a name of your choice. You can add such an option by
61 modifying @func{parse_options} in @file{threads/init.c}.
63 The introduction describes additional coding style requirements
69 The Pintos source code uses a few features of the ``C99'' standard
70 library that were not in the original 1989 standard for C. Many
71 programmers are unaware of these feature, so we will describe them. The
72 new features used in Pintos are
73 mostly in new headers:
77 Defines macros @code{bool}, a 1-bit type that takes on only the values
78 0 and 1, @code{true}, which expands to 1, and @code{false}, which
82 On systems that support them, this header defines types
83 @code{int@var{n}_t} and @code{uint@var{n}_t} for @var{n} = 8, 16, 32,
84 64, and possibly other values. These are 2's complement signed and unsigned
85 types, respectively, with the given number of bits.
87 On systems where it is possible, this header also defines types
88 @code{intptr_t} and @code{uintptr_t}, which are integer types big
89 enough to hold a pointer.
91 On all systems, this header defines types @code{intmax_t} and
92 @code{uintmax_t}, which are the system's signed and unsigned integer
93 types with the widest ranges.
95 For every signed integer type @code{@var{type}_t} defined here, as well
96 as for @code{ptrdiff_t} defined in @file{<stddef.h>}, this header also
97 defines macros @code{@var{TYPE}_MAX} and @code{@var{TYPE}_MIN} that
98 give the type's range. Similarly, for every unsigned integer type
99 @code{@var{type}_t} defined here, as well as for @code{size_t} defined
100 in @file{<stddef.h>}, this header defines a @code{@var{TYPE}_MAX}
101 macro giving its maximum value.
104 @file{<stdint.h>} provides no straightforward way to format
105 the types it defines with @func{printf} and related functions. This
106 header provides macros to help with that. For every
107 @code{int@var{n}_t} defined by @file{<stdint.h>}, it provides macros
108 @code{PRId@var{n}} and @code{PRIi@var{n}} for formatting values of
109 that type with @code{"%d"} and @code{"%i"}. Similarly, for every
110 @code{uint@var{n}_t}, it provides @code{PRIo@var{n}},
111 @code{PRIu@var{n}}, @code{PRIu@var{x}}, and @code{PRIu@var{X}}.
113 You use these something like this, taking advantage of the fact that
114 the C compiler concatenates adjacent string literals:
116 #include <inttypes.h>
118 int32_t value = @dots{};
119 printf ("value=%08"PRId32"\n", value);
122 The @samp{%} is not supplied by the @code{PRI} macros. As shown
123 above, you supply it yourself and follow it by any flags, field
127 The @func{printf} function has some new type modifiers for printing
132 For @code{intmax_t} (e.g.@: @samp{%jd}) or @code{uintmax_t} (e.g.@:
136 For @code{size_t} (e.g.@: @samp{%zu}).
139 For @code{ptrdiff_t} (e.g.@: @samp{%td}).
142 Pintos @func{printf} also implements a nonstandard @samp{'} flag that
143 groups large numbers with commas to make them easier to read.
146 @node Unsafe String Functions
147 @section Unsafe String Functions
149 A few of the string functions declared in the standard
150 @file{<string.h>} and @file{<stdio.h>} headers are notoriously unsafe.
151 The worst offenders are intentionally not included in the Pintos C
156 When used carelessly this function can overflow the buffer reserved
157 for its output string. Use @func{strlcpy} instead. Refer to
158 comments in its source code in @code{lib/string.c} for documentation.
161 This function can leave its destination buffer without a null string
162 terminator. It also has performance problems. Again, use
166 Same issue as @func{strcpy}. Use @func{strlcat} instead.
167 Again, refer to comments in its source code in @code{lib/string.c} for
171 The meaning of its buffer size argument is surprising.
172 Again, use @func{strlcat}.
175 Uses global data, so it is unsafe in threaded programs such as
176 kernels. Use @func{strtok_r} instead, and see its source code in
177 @code{lib/string.c} for documentation and an example.
180 Same issue as @func{strcpy}. Use @func{snprintf} instead. Refer
181 to comments in @code{lib/stdio.h} for documentation.
184 Same issue as @func{strcpy}. Use @func{vsnprintf} instead.
187 If you try to use any of these functions, the error message will give
188 you a hint by referring to an identifier like
189 @code{dont_use_sprintf_use_snprintf}.