summary refs log tree commit diff
path: root/manual/=stddef.texi
diff options
context:
space:
mode:
Diffstat (limited to 'manual/=stddef.texi')
-rw-r--r--manual/=stddef.texi81
1 files changed, 81 insertions, 0 deletions
diff --git a/manual/=stddef.texi b/manual/=stddef.texi
new file mode 100644
index 0000000000..28d4b26f33
--- /dev/null
+++ b/manual/=stddef.texi
@@ -0,0 +1,81 @@
+@node Common Definitions, Memory Allocation, Error Reporting, Top
+@chapter Common Definitions
+
+There are some miscellaneous data types and macros that are not part of
+the C language kernel but are nonetheless almost universally used, such
+as the macro @code{NULL}.  In order to use these type and macro
+definitions, your program should include the header file
+@file{stddef.h}.
+@pindex stddef.h
+
+@comment stddef.h
+@comment ANSI
+@deftp {Data Type} ptrdiff_t
+This is the signed integer type of the result of subtracting two
+pointers.  For example, with the declaration @code{char *p1, *p2;}, the
+expression @code{p2 - p1} is of type @code{ptrdiff_t}.  This will
+probably be one of the standard signed integer types (@code{short int},
+@code{int} or @code{long int}), but might be a nonstandard type that
+exists only for this purpose.
+@end deftp
+
+@comment stddef.h
+@comment ANSI
+@deftp {Data Type} size_t
+This is an unsigned integer type used to represent the sizes of objects.
+The result of the @code{sizeof} operator is of this type, and functions
+such as @code{malloc} (@pxref{Unconstrained Allocation}) and
+@code{memcpy} (@pxref{Copying and Concatenation}) that manipulate
+objects of arbitrary sizes accept arguments of this type to specify
+object sizes.
+@end deftp
+
+In the GNU system @code{size_t} is equivalent to one of the types 
+@code{unsigned int} and @code{unsigned long int}.  These types have
+identical properties on the GNU system, and for most purposes, you
+can use them interchangeably.  However, they are distinct types, 
+and in certain contexts, you may not treat them as identical.  For
+example, when you specify the type of a function argument in a 
+function prototype, it makes a difference which one you use.  If
+the system header files declare @code{malloc} with an argument
+of type @code{size_t} and you declare @code{malloc} with an argument
+of type @code{unsigned int}, you will get a compilation error if
+@code{size_t} happens to be @code{unsigned long int} on your system.
+To avoid any possibility of error, when a function argument is
+supposed to have type @code{size_t}, always write the type as
+@code{size_t}, and make no assumptions about what that type might
+actually be.
+
+@strong{Compatibility Note:}  Types such as @code{size_t} are new
+features of ANSI C.  Older, pre-ANSI C implementations have
+traditionally used @code{unsigned int} for representing object sizes
+and @code{int} for pointer subtraction results.
+
+@comment stddef.h
+@comment ANSI
+@deftypevr Macro {void *} NULL
+@cindex null pointer
+This is a null pointer constant.  It can be assigned to any pointer
+variable since it has type @code{void *}, and is guaranteed not to
+point to any real object.  This macro is the best way to get a null
+pointer value.  You can also use @code{0} or @code{(void *)0} as a null
+pointer constant, but using @code{NULL} makes the purpose of the
+constant more evident.  
+
+When passing a null pointer as an argument to a function for which there
+is no prototype declaration in scope, you should explicitly cast
+@code{NULL} or @code{0} into a pointer of the appropriate type.  Again,
+this is because the default argument promotions may not do the right
+thing.
+@end deftypevr
+
+@comment stddef.h
+@comment ANSI
+@deftypefn {Macro} size_t offsetof (@var{type}, @var{member})
+This expands to a integer constant expression that is the offset of the
+structure member named @var{member} in a @code{struct} of type
+@var{type}.  For example, @code{offsetof (struct s, elem)} is the
+offset, in bytes, of the member @code{elem} in a @code{struct s}.  This
+macro won't work if @var{member} is a bit field; you get an error from
+the C compiler in that case.
+@end deftypefn