Put a @table around @include summary.out.
[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 In the GNU system @code{size_t} is equivalent to one of the types 
34 @code{unsigned int} and @code{unsigned long int}.  These types have
35 identical properties on the GNU system, and for most purposes, you
36 can use them interchangeably.  However, they are distinct types, 
37 and in certain contexts, you may not treat them as identical.  For
38 example, when you specify the type of a function argument in a 
39 function prototype, it makes a difference which one you use.  If
40 the system header files declare @code{malloc} with an argument
41 of type @code{size_t} and you declare @code{malloc} with an argument
42 of type @code{unsigned int}, you will get a compilation error if
43 @code{size_t} happens to be @code{unsigned long int} on your system.
44 To avoid any possibility of error, when a function argument is
45 supposed to have type @code{size_t}, always write the type as
46 @code{size_t}, and make no assumptions about what that type might
47 actually be.
48
49 @strong{Compatibility Note:}  Types such as @code{size_t} are new
50 features of ANSI C.  Older, pre-ANSI C implementations have
51 traditionally used @code{unsigned int} for representing object sizes
52 and @code{int} for pointer subtraction results.
53
54 @comment stddef.h
55 @comment ANSI
56 @deftypevr Macro {void *} NULL
57 @cindex null pointer
58 This is a null pointer constant.  It can be assigned to any pointer
59 variable since it has type @code{void *}, and is guaranteed not to
60 point to any real object.  This macro is the best way to get a null
61 pointer value.  You can also use @code{0} or @code{(void *)0} as a null
62 pointer constant, but using @code{NULL} makes the purpose of the
63 constant more evident.  
64
65 When passing a null pointer as an argument to a function for which there
66 is no prototype declaration in scope, you should explicitly cast
67 @code{NULL} or @code{0} into a pointer of the appropriate type.  Again,
68 this is because the default argument promotions may not do the right
69 thing.
70 @end deftypevr
71
72 @comment stddef.h
73 @comment ANSI
74 @deftypefn {Macro} size_t offsetof (@var{type}, @var{member})
75 This expands to a integer constant expression that is the offset of the
76 structure member named @var{member} in a @code{struct} of type
77 @var{type}.  For example, @code{offsetof (struct s, elem)} is the
78 offset, in bytes, of the member @code{elem} in a @code{struct s}.  This
79 macro won't work if @var{member} is a bit field; you get an error from
80 the C compiler in that case.
81 @end deftypefn