glibc/manual/=stddef.texi

@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 ISO
@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 ISO
@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 @w{ISO 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 ISO
@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 ISO
@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