projects
/
pintos-anon
/ blobdiff
commit
grep
author
committer
pickaxe
?
search:
re
summary
|
shortlog
|
log
|
commit
|
commitdiff
|
tree
raw
|
inline
| side by side
Credit Mendel.
[pintos-anon]
/
doc
/
standards.texi
diff --git
a/doc/standards.texi
b/doc/standards.texi
index 60aa21aa8afcaf82c348618227d3b51a83be6c0f..7af266e9c10b9cecb5be44f8ae190acf9a8048ef 100644
(file)
--- a/
doc/standards.texi
+++ b/
doc/standards.texi
@@
-41,6
+41,11
@@
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.
different style won't cause actual problems, but it's ugly to see
gratuitous differences in style from one function to another.
+Pintos comments sometimes refer to outside 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}).
+
@node Conditional Compilation
@section Conditional Compilation
@node Conditional Compilation
@section Conditional Compilation
@@
-65,13
+70,13
@@
There are a few exceptions:
@itemize @bullet
@item
@itemize @bullet
@item
-Problem 1-2, @
code{thread_join()
}. Some other code expects
+Problem 1-2, @
func{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
@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
+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.
specify for that part. @xref{Problem 1-4 Advanced Scheduler}, for
details.
@@
-126,7
+131,7
@@
macro giving its maximum value.
@item <inttypes.h>
@file{<stdint.h>} is useful on its own, but it provides no way to pass
@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
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
@@
-140,7
+145,7
@@
the C compiler concatenates adjacent string literals:
#include <inttypes.h>
@dots{}
int32_t value = @dots{};
#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
@end example
@noindent
The @samp{%} is not supplied by the @code{PRI} macros. As shown
@@
-148,7
+153,7
@@
above, you supply it yourself and follow it by any flags, field
widths, etc.
@item <stdio.h>
widths, etc.
@item <stdio.h>
-The @f
ile{printf()
} function has some new type modifiers for printing
+The @f
unc{printf
} function has some new type modifiers for printing
standard types:
@table @samp
standard types:
@table @samp
@@
-162,6
+167,9
@@
For @code{size_t} (e.g.@: @samp{%zu}).
@item t
For @code{ptrdiff_t} (e.g.@: @samp{%td}).
@end table
@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
@end table
@node Unsafe String Functions
@@
-172,37
+180,37
@@
A few of the string functions declared in the standard
The worst offenders are intentionally not included in the Pintos C
library:
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
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.
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
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}, but substitute @func{strlcat
}.
Again, refer to comments in its source code in @code{lib/string.c} for
documentation.
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.
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
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.
@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.
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
@end table
If you try to use any of these functions, you should get a hint from