.TH pointer "" "" "C Language"
.PC
.PP
.II "initialization of pointers"
.II "pointer type"
.II "type, pointer"
.II "referenced type"
.II "type, referenced"
.II "pointer type derivation"
.II "function, pointer to"
.II "null pointer"
.II "wild pointer"
.II "dereferencing, pointer"
.II "pointer dereferencing"
.II "pointer-type mismatch"
A
.I pointer
is an object whose value is the address of another object.
The name \*(QLpointer\*(QR derives from the fact that its contents
\*(QLpoint to\*(QR another object.
A pointer may point to any type, complete or incomplete,
including another pointer.
It may also point to a function, or to nowhere.
.PP
The term
.I "pointer type"
refers to the object of a pointer.
The object to which a pointer points is called the
.IR "referenced type" .
For example, an
.B "int *"
(\*(QLpointer to \fBint\fR\*(QR) is a pointer type; the referenced type is
.BR int .
Constructing a pointer type from a referenced type is called
.IR "pointer type derivation" .
.SH "The Null Pointer"
A pointer that points to nowhere is a
.IR "null pointer" .
The macro
.BR NULL ,
which is defined in the header
.BR stdio.h ,
defines the null
pointer.
The null pointer is an integer constant with the value
zero.
It compares unequal to a pointer to any object or
function.
.SH "Declaring a Pointer"
To declare a pointer, use the indirection operator \*(Ql*\*(Qr.
For example, the declaration
.DM
	int *pointer;
.DE
.PP
declares that the variable
.B pointer
holds the address of an \fBint\fR-length object.
Likewise, the declaration
.DM
	int **pointer;
.DE
.PP
declares that
.B pointer
holds the address of a pointer whose contents, in turn, point to an
\fBint\fR-length object.
.PP
Failure to declare a function that returns a pointer
will result in that function being implicitly declared as an
.BR int .
This does not cause an error on microprocessors in which an
.B int
and a pointer have the same size; however, if you transport this code
to a microprocessor in which an
.B int
consists of 16 bits and a pointer consists of 32 bits,
the pointer will be truncated truncated to 16 bits and
the program probably will fail.
.PP
C allows pointers and integers to be compared or converted
to each other without restriction.
The \*(CO C compiler
flags such conversions with the strict message
.DM
	integer pointer pun
.DE
.PP
and comparisons with the strict message
.DM
	integer pointer comparison
.DE
.PP
These problems should be corrected if you want your code to
be portable to other computing environments.
.PP
See
.B "C language"
for more information.
.SH "Wild Pointers"
Pointers are omnipresent in C.
C also allows you to use a pointer to read or write
the object to which the
pointer points;
this is called
.IR "pointer dereferencing" .
Because a pointer can point to any place within memory, it is possible
to write C code that generates unpredictable results, corrupts itself,
or even obliterates the operating system
if running in unprotected mode.
A pointer that aims where it ought not is called a
.IR "wild pointer" .
.PP
When a program declares a pointer, space is set aside in memory for it.
However, this space has not yet been filled with the address of an object.
To fill a pointer with the address of the object you wish to access is called
.I initializing
it.
A wild pointer, as often as not, is one that is not properly initialized.
.PP
Normally, to initialize a pointer means to fill it with a meaningful address.
For example, the following initializes a pointer:
.DM
	int number;
	int *pointer;
	   . . .
	pointer = &number;
.DE
.PP
The address operator \*(Ql&\*(Qr specifies that you want the address
of an object rather than its contents.
Thus,
.B pointer
is filled with the address of
.BR number ,
and it can now be used to access the contents of
.BR number .
.PP
The initialization of a string is somewhat different than the initialization
of a pointer to an integer object.
For example,
.DM
	char *string = "This is a string."
.DE
.PP
declares that
.B string
is a pointer to a
.BR char .
It then stores the string literal
.B "This is a string"
in memory and fills
.B string
with the address of its first character.
.B string
can then be passed to functions to access the string, or you can step through
the string by incrementing
.B string
until its contents point to the null character at the end of the string.
.PP
Another way to initialize a pointer is to fill it with a value returned by
a function that returns a pointer.
For example, the code
.DM
	extern char *malloc(size_t variable);
	char *example;
	   . . .
	example = malloc(50);
.DE
.PP
uses the function
.B malloc
to allocate 50 bytes of dynamic memory and then initializes
.B example
to the address that
.B malloc
returns.
.SH "Reading What a Pointer Points To"
The indirection operator \*(Ql*\*(Qr can be used to read the object
to which a pointer points.
For example,
.DM
	int number;
	int *pointer;
	   . . .
	pointer = &number;
	   . . .
	printf("%d\en", *pointer);
.DE
.PP
uses
.B pointer
to access the contents of
.BR number .
.PP
When a pointer points to a structure, the elements within the structure
can be read by using the structure offset operator \*(Ql->\*(Qr.
See the entry for
.B operators
for more information.
.SH "Pointers to Functions"
A pointer can also contain the address of a function.
For example,
.DM
	char *(*example)();
.DE
.PP
declares
.B example
to be a pointer to a function that returns a pointer to a
.BR char .
.PP
This declaration is quite different from:
.DM
	char **different();
.DE
.PP
The latter declares that
.B different
is a function that returns a pointer to a pointer to a
.BR char .
.PP
The following demonstrates how to call a function via a pointer:
.DM
	(*example)(\fIarg1\^\fP, \fIarg2\^\fP);
.DE
.PP
Here, the \*(Ql*\*(Qr takes the contents of the pointer, which in this case
is the address of the function, and uses that address to pass to a function
its list of arguments.
.PP
A pointer to a function can be passed as an argument to another function.
The functions
.B bsearch
and
.B qsort
each take a function pointer as an argument.
A program may also use arrays of pointers to functions.
.SH "void *"
.B "void *"
is the generic pointer; it replaces
.B "char *"
in that role.
A pointer may be cast to
.B "void *"
and then back to its original type without any change in its value.
.B "void *"
is also aligned for any type in the execution environment.
Please note that \*(CO's C compiler does not yet recognize the type
.BR "void *" .
.PP
In Kernighan and Ritchie C, character pointers are equivalent to
.BR "void *" .
To convert a program to use
.BR "void *" ,
rewrite the sources so that instances of
.DM
	char *foo(bar);
.DE
.PP
is replaced by:
.DM
	VOID_T *foo(bar);
.DE
.PP
Be sure that you do not replace legitimate
\fBchar *\fRs \(em that is, pointers that actually point to character strings.
Then put the code
.DM
	#if defined(__ANSI__) || defined(__GNUC__)
	typedef void VOID_T
	#else
	typedef char VOID_T
	#endif
.DE
.PP
into an application-owned header file that is included by every source file.
.SH "Pointer Conversion"
One type of pointer may be converted, or
.IR cast ,
to another.
For example, a pointer to a
.B char
may be cast to a pointer to an
.BR int ,
and vice versa.
.PP
The \*(AS states that any pointer can be cast to type
.B "void *"
and back again without its value being affected in any way.
(Once again, please note that \*(CO's C compiler does not yet recognize the type
.BR "void *" .)
Likewise, any pointer of a scalar type may be cast to its
corresponding
.B const
or
.B volatile
version.
The qualified pointers are equivalent to their unqualified originals.
.PP
Pointers to different data types are compatible in expressions, but only if
they are cast appropriately.
Using them without casting produces a
.IR "pointer-type mismatch" .
The translator should produce a diagnostic message when it detects
this condition.
.SH "Pointer Arithmetic"
Arithmetic may be performed on all pointers to scalar types, i.e.,
pointers to \fBchar\fRs or \fBint\fR.
Pointer arithmetic is quite limited and consists of the following:
.IP \fB1.\fR 0.3i
One pointer may be subtracted from another.
.IP \fB2.\fR
An
.B int
or a
.BR long ,
either variable or constant, may be added to a pointer or
subtracted from it.
.IP \fB3.\fR
The operators
.B ++
or
.B --
may be used to increment or decrement a pointer.
.PP
No other pointer arithmetic is permitted.
No arithmetic can be performed on pointers to non-scalar objects,
e.g., pointers to functions.
.PP
When an
.B int
or
.B long
is added to a pointer,
it is first multiplied by the length
of what the pointer is declared as pointing to.
Thus, if a pointer to an
.B int
is incremented by two, it points down two more
.BR int s,
not two more characters.
The following program demonstrates this feature:
.DM
char *pc = "Welcome";
int array[5] = { 1, 2, 3, 4, 5 };
int  *pi = array; 
.DE
.DM
main()
{
.ta 0.5i 1.5i
	pc += 2;	/* pc points to  'l' */
	pi += 2;	/* pi points to 3 */
}
.DE
.\".SH "i8086 Pointers"
.\"Intel designed the i8086 to use a segmented architecture.
.\"This means that the i8086 divides memory into 64-kilobyte segments.
.\"To program the i8086 requires that you use a specific
.\".IR "memory model" ,
.\"which describes how the segments of memory are to be organized.
.SH "See Also"
.Xr "C language" c language
data formats
.Xr "operators," operators
.Xr "portability," portabili
.Xr "Programming COHERENT" programmi
.R
.br
\*(AS, \(sc6.1.2.5, \(sc6.2.2.1, \(sc6.2.2.3, \(sc6.3.2.2-3, \(sc6.5.4.1
