Fixed some formatting and indexing problems.
[kopensolaris-gnu/glibc.git] / manual / =stddef.texi
1 @node Common Definitions
2 @chapter Common Definitions
3
4 There are some miscellaneous data types and macros that are not part of
5 the C language kernel but are nonetheless almost universally used, such
6 as the macro @code{NULL}.  In order to use these type and macro
7 definitions, your program should include the header file
8 @file{stddef.h}.
9 @pindex stddef.h
10
11 @comment stddef.h
12 @comment ANSI
13 @deftp {Data Type} ptrdiff_t
14 This is the signed integer type of the result of subtracting two
15 pointers.  For example, with the declaration @code{char *p1, *p2;}, the
16 expression @code{p2 - p1} is of type @code{ptrdiff_t}.  This will
17 probably be one of the standard signed integer types (@code{short int},
18 @code{int} or @code{long int}), but might be a nonstandard type that
19 exists only for this purpose.
20 @end deftp
21
22 @comment stddef.h
23 @comment ANSI
24 @deftp {Data Type} size_t
25 This is an unsigned integer type used to represent the sizes of objects.
26 The result of the @code{sizeof} operator is of this type, and functions
27 such as @code{malloc} (@pxref{Unconstrained Allocation}) and
28 @code{memcpy} (@pxref{Copying and Concatenation}) that manipulate
29 objects of arbitrary sizes accept arguments of this type to specify
30 object sizes.
31 @end deftp
32
33 As a general concern with derived data types such as these, you need to
34 be careful either to consistently declare variables and function
35 prototypes that can receive values of these types with the derived
36 types, or else to use an explicit cast on the value.  For example, you
37 shouldn't use @code{size_t} interchangably either with @code{unsigned
38 int} or @code{unsigned long int}, since it might be either one of those.
39 This is a particular problem when passing values to functions for which
40 there is no prototype declared in scope, since the default argument
41 promotions can differ from implementation to implementation.  Another
42 problem is that there aren't any constants in @file{limits.h} to tell
43 you what the minimum and maximum values for these data types are.
44
45 @strong{Compatibility Note:}  Types such as @code{size_t} are new
46 features of ANSI C.  Older, pre-ANSI C implementations have
47 traditionally used @code{unsigned int} for representing object sizes
48 and @code{int} for pointer subtraction results.
49
50 @comment stddef.h
51 @comment ANSI
52 @defvr {Macro} NULL
53 @cindex null pointer
54 This is a null pointer constant.  It can be assigned to any pointer
55 variable since it has type @code {void *}, and is guaranteed not to
56 point to any real object.  This macro is the best way to get a null
57 pointer value.  You can also use @code{0} or @code{(void *)0} as a null
58 pointer constant, but using @code{NULL} makes the purpose of the
59 constant more evident.  
60
61 When passing a null pointer as an argument to a function for which there
62 is no prototype declaration in scope, you should explicitly cast
63 @code{NULL} or @code{0} into a pointer of the appropriate type.  Again,
64 this is because the default argument promotions may not do the right
65 thing.
66 @end defvr
67
68 @comment stddef.h
69 @comment ANSI
70 @deftypefn {Macro} size_t offsetof (@var{type}, @var{member})
71 This expands to a integer constant expression that is the offset of the
72 structure member named @var{member} in a @code{struct} of type
73 @var{type}.  For example, @code{offsetof (struct s, elem)} is the
74 offset, in bytes, of the member @code{elem} in a @code{struct s}.  This
75 macro won't work if @var{member} is a bit field; you get an error from
76 the C compiler in that case.
77 @end deftypefn