NSPR Reference: Chapter 2 NSPR Types
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

NSPR Reference Previous Contents Next

## Chapter 2 NSPR Types

This chapter describes the most common NSPR types. Other chapters describe more specialized types when describing the functions that use them.

Calling Convention Types are used for externally visible functions and globals.

- Algebraic Types of various lengths are used for integer algebra.

- Miscellaneous Types are used for representing size, pointer difference, Boolean values, and return values.

For information on naming conventions for NSPR types, functions, and macros, see NSPR Naming Conventions.

## Calling Convention Types

These types are used to support cross-platform declarations of prototypes and implementations:

`PR_EXTERN` is used for definitions of external functions or variables.

- `PR_IMPLEMENT` is used for declarations of external functions or variables.

- `PR_CALLBACK` is used for definitions and declarations of functions that are called via function pointers. A typical example is a function implemented in an application but called from a shared library.

Here are some simple examples of the use of these types:

In `dowhim.h`:

    PR_EXTERN( void ) DoWhatIMean( void );

    static void PR_CALLBACK RootFunction(void *arg);

In `dowhim.c`:

    PR_IMPLEMENT( void ) DoWhatIMean( void ) { return; };

    PRThread *thread = PR_CreateThread(..., RootFunction, ...);

#### PR_EXTERN

Used to define the prototypes for functions or variables that are to be exported from a shared library.

##### Syntax

    #include <prtypes.h>

    PR_EXTERN(type) prototype

##### Description

`PR_EXTERN` is used to define externally visible routines and globals. For syntax details for each platform, see `prtypes.h`. The macro includes the proper specifications to declare the target `extern` and set up other required linkages.

##### Warning

Some platforms do not allow the use of the underscore character (`_`) as the first character of an exported symbol.

#### PR_IMPLEMENT

Used to define implementations of symbols that are to be exported from a shared library.

##### Syntax

    #include <prtypes.h>

    PR_IMPLEMENT(type) implementation

##### Description

`PR_IMPLEMENT` is used to define implementations of externally visible routines and globals. For syntax details for each platform, see `prtypes.h`.

##### Warning

Some platforms do not allow the use of the underscore character (`_`) as the first character of an exported symbol.

#### PR_CALLBACK

Used to define pointers to functions that will be implemented by the client but called from a (different) shared library.

##### Syntax

    #include <prtypes.h>

type `PR_CALLBACK` implementation

##### Description

Functions that are implemented in an application (or shared library) that are intended to be called from another shared library (such as NSPR) must be declared with the `PR_CALLBACK` attribute. Normally such functions are passed by reference (pointer to function). The `PR_CALLBACK` attribute is included as part of the function's definition between its return value type and the function's name.

## Algebraic Types

NSPR provides the following type definitions with unambiguous bit widths for algebraic operations:

8-, 16-, and 32-bit Integer Types
64-bit Integer Types
Floating-Point Number Type

For convenience, NSPR also provides type definitions with platform-dependent bit widths:

Native OS Integer Types

### 8-, 16-, and 32-bit Integer Types

#### Signed Integers

#### PRInt8

Guaranteed to be a signed 8-bit integer on all platforms.

##### Syntax

    #include <prtypes.h>

    typedef definition PRInt8;

#### PRInt16

Guaranteed to be a signed 16-bit integer on all platforms.

##### Syntax

    #include <prtypes.h>

    typedef definition PRInt16;

#### PRInt32

Guaranteed to be a signed 32-bit integer on all platforms.

##### Syntax

    #include <prtypes.h>

    typedef definition PRInt32;

##### Description

May be defined as an `int` or a `long`, depending on the platform. For syntax details for each platform, see `prtypes.h`.

#### Unsigned Integers

#### PRUint8

Guaranteed to be an unsigned 8-bit integer on all platforms. There is no type equivalent to a plain `char`.

##### Syntax

    #include <prtypes.h>

    typedef definition PRUint8;

#### PRUint16

Guaranteed to be an unsigned 16-bit integer on all platforms.

##### Syntax

    #include <prtypes.h>

    typedef definition PRUint16;

#### PRUint32

Guaranteed to be an unsigned 32-bit integer on all platforms.

##### Syntax

    #include <prtypes.h>

    typedef definition PRUint32;

##### Description

May be defined as an unsigned `int` or an unsigned `long`, depending on the platform. For syntax details for each platform, see `prtypes.h`.

### 64-bit Integer Types

Different platforms treat 64-bit numeric fields in different ways. Some systems require emulation of 64-bit fields by using two 32-bit numeric fields bound in a structure. Since the types (`long long` versus `struct LONGLONG`) are not type compatible, NSPR defines macros to manipulate 64-bit numeric fields. These macros are defined in `prlong.h`. Conscientious use of these macros ensures portability of code to all the platforms supported by NSPR and still provides optimal behavior on those systems that treat `long long` values directly.

#### PRInt64

Guaranteed to be a signed 64-bit integer on all platforms.

##### Syntax

    #include <prtypes.h>

    typedef definition PRInt64;

##### Description

May be defined in several different ways, depending on the platform. For syntax details for each platform, see `prtypes.h`.

#### PRUint64

Guaranteed to be an unsigned 64-bit integer on all platforms.

##### Syntax

    #include <prtypes.h>

    typedef definition PRUint64;

##### Description

May be defined in several different ways, depending on the platform. For syntax details for each platform, see `prtypes.h`.

### Floating-Point Number Type

The NSPR floating-point type is always 64 bits.

##### Syntax

    #include <prtypes.h>

    typedef double PRFloat64;

### Native OS Integer Types

These types are most appropriate for automatic variables. They are guaranteed to be at least 16 bits, though various architectures may define them to be wider (for example, 32 or even 64 bits). These types are never valid for fields of a structure.

##### Syntax

    #include <prtypes.h>

    typedef int PRIntn;
    typedef unsigned int PRUintn;

## Miscellaneous Types

Size Type
Pointer Difference Types
Boolean Types
Status Type for Return Values

### Size Type

#### PRSize

A type for representing the size of an object (not the size of a pointer). This is the same as the corresponding type in `lib.c`.

##### Syntax

    #include <prtypes.h>

    typedef size_t PRSize;

### Pointer Difference Types

Types for pointer difference. Variables of these types are suitable for storing a pointer or pointer subtraction. These are the same as the corresponding types in `libc`.

#### PRPtrdiff

Signed pointer difference type.

##### Syntax

    #include <prtypes.h>

    typedef ptrdiff_t PRPtrdiff;

#### PRUptrdiff

Unsigned pointer difference type.

##### Syntax

    #include <prtypes.h>

    typedef unsigned long PRUptrdiff;

### Boolean Types

Type and constants for Boolean values.

#### PRBool

Boolean value.

##### Syntax

    #include <prtypes.h>

    typedef enum { PR_FALSE = 0, PR_TRUE = 1 } PRBool;

##### Description

Use `PRBool` for variables and parameter types. Use `PR_FALSE` and `PR_TRUE` for clarity of target type in assignments and actual arguments. Use `if (bool)`, `while (!bool)`, `(bool) ? x : y`, and so on to test Boolean values, just as you would C `int`-valued conditions.

#### PRPackedBool

Packed Boolean value.

##### Syntax

    #include <prtypes.h>

    typedef PRUint8 PRPackedBool;

##### Description

Use `PRPackedBool` within structures where bit fields are not desirable but minimum and consistent overhead matters.

### Status Type for Return Values

#### PRStatus

Type for status code returned by some functions.

##### Syntax

    #include <prtypes.h>

    typedef enum { PR_FAILURE = -1, PR_SUCCESS = 0 } PRStatus;

Previous Contents Next

Last Updated May 18, 2001