manual/=stddef.texi

   1 @node Common Definitions, Memory Allocation, Error Reporting, Top
   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