NSPR Reference: Chapter 14 Date and Time
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 14 Date and Time

This chapter describes the date and time functions in NSPR.

NSPR represents time in two ways, absolute time and clock/calendar time. NSPR provides types and constants for both representations, and functions to convert time values between the two.

Absolute time representation treats time instants as points along the time line. A time instant is represented by its position on the time line relative to the origin, called the epoch. NSPR defines the epoch to be midnight (00:00:00) 1 January 1970 UTC (Coordinated Universal Time). In this form, time is just a point on the time line. There is no notion of time zone.

- Clock/calendar time, used for human interfaces, represents time in the familiar year, month, day, hour, minute, second components. In this form, the time zone information is important. For example, without specifying the time zone, the time 8:00AM 1 May 1998 is ambiguous. The NSPR data type for clock/calendar time, called an exploded time, has the time zone information in it, so that its corresponding point in absolute time is uniquely specified.

Note that absolute and clock times are not normally used in timing operations. For functions that deal with the measurement of elapsed time and with timeouts, see Chapter 13 "Interval Timing."

Types and Constants
Time Parameter Callback Functions
Functions

## Types and Constants

Types and constants defined for NSPR dates and times are:

`Macros for Time Unit Conversion``
` `PRTime``
` `PRTimeParameters``
` `PRTimeParameters```

In addition, callback functions are defined for determining time zone information:

Time Parameter Callback Functions

#### Macros for Time Unit Conversion

Macros for converting between seconds, milliseconds, microseconds, and nanoseconds.

##### Syntax

    #include <prtime.h>

    #define PR_MSEC_PER_SEC  1000UL
    #define PR_USEC_PER_SEC  1000000UL
    #define PR_NSEC_PER_SEC  1000000000UL
    #define PR_USEC_PER_MSEC 1000UL
    #define PR_NSEC_PER_MSEC 1000000UL

##### Description

These macros are provided for convenience, to improve the readability of your code as well as to avoid mistakes in counting the number of zeros. `SEC` stands for seconds, `MSEC` for milliseconds, `USEC` for microseconds, and `NSEC` for nanoseconds.

#### PRTime

A representation of absolute times.

##### Syntax

    #include <prtime.h>

    typedef PRInt64 PRTime;

##### Description

This type is a 64-bit integer representing the number of microseconds since the NSPR epoch, midnight (00:00:00) 1 January 1970 Coordinated Universal Time (UTC). A time after the epoch has a positive value, and a time before the epoch has a negative value.

In NSPR, we use the more familiar term Greenwich Mean Time (GMT) in place of UTC. Although UTC and GMT are not exactly the same in their precise definitions, they can generally be treated as if they were.

Because `PRTime` is a 64-bit integer, you must use the LL macros defined in `prlong.h` to manipulate `PRTime` values. (See Chapter 18 "Long Long (64-bit) Integers)"

#### PRTimeParameters

A representation of time zone information.

##### Syntax

    #include <prtime.h>

    typedef struct PRTimeParameters {
        PRInt32 tp_gmt_offset;
        PRInt32 tp_dst_offset;
    } PRTimeParameters;

##### Description

Each geographic location has a standard time zone, and if daylight saving time (DST) is practiced, a daylight time zone. The `PRTimeParameters` structure represents the local time zone information in terms of the offset (in seconds) from GMT. The overall offset is broken into two components:

`tp_gmt_offset`: The offset of the local standard time from GMT.

- `tp_dst_offset`: If daylight savings time (DST) is in effect, the DST adjustment from the local standard time. This is most commonly 1 hour, but may also be 30 minutes or some other amount. If DST is not in effect, the `tp_dst_offset` component is 0.

For example, the US Pacific Time Zone has both a standard time zone (Pacific Standard Time, or PST) and a daylight time zone (Pacific Daylight Time, or PDT).

In PST, the local time is 8 hours behind GMT, so `tp_gmt_offset` is -28800 seconds. `tp_dst_offset` is 0, indicating that daylight saving time is not in effect.

- In PDT, the clock is turned forward by one hour, so the local time is 7 hours behind GMT. This is broken down as -8 + 1 hours, so `tp_gmt_offset` is
  -28800 seconds, and `tp_dst_offset` is 3600 seconds.

A second example is Japan, which is 7 hours ahead of GMT. Japan does not use daylight saving time, so the only time zone is Japan Standard Time (JST). In JST `tp_gmt_offset` is 25200 seconds, and `tp_dst_offset` is 0.

#### PRExplodedTime

A clock/calendar representation of times.

##### Syntax

    #include <prtime.h>

    typedef struct PRExplodedTime {
        PRInt32 tm_usec;
        PRInt32 tm_sec;
        PRInt32 tm_min;
        PRInt32 tm_hour;
        PRInt32 tm_mday;
        PRInt32 tm_month;
        PRInt16 tm_year;
        PRInt8 tm_wday;
        PRInt16 tm_yday;
        PRTimeParameters tm_params;
    } PRExplodedTime;

##### Description

The `PRExplodedTime` structure represents clock/calendar time. `PRExplodedTime` has the familiar time components: year, month, day of month, hour, minute, second. It also has a microsecond component, as well as the day of week and the day of year. In addition, `PRExplodedTime` `PRTimeParameters` structure representing the local time zone information, so that the time point is non-ambiguously specified.

The essential members of `PRExplodedTime` are:

`tm_year`: absolute year, AD. (Note that we do not count from 1900.)

- `tm_month`: number of months past `tm_year`. The range is [0, 11]. 0 is January and 11 is December.

- `tm_mday`: the day of month. The range is [1, 31]. Note that it starts from 1 as opposed to 0.

- `tm_hour`: number of hours past `tm_mday`. The range is [0, 23].

- `tm_min`: number of minutes past `tm_hour`. The range is [0, 59].

- `tm_sec`: number of seconds past `tm_min`. The range is [0, 61]. The values 60 and 61 are for accommodating up to two leap seconds.

- `tm_usec`: number of microseconds past `tm_sec`. The range is [0, 999999].

- `tm_params`: a `PRTimeParameters` structure representing the local time zone information.

The nonessential members of `PRExplodedTime` are:

`tm_wday`: day of week. The range is [0, 6]. 0 is Sunday, 1 is Monday, and 6 is Saturday.

- `tm_yday`: day of year. The range is [0, 365]. 0 is the 1st of January.

On input to NSPR functions, only the essential members of `PRExplodedTime` must be specified. The two nonessential members (day of week and day of year) are ignored by NSPR functions as input. When an NSPR function returns a `PRExplodedTime` object or sets a `PRExplodedTime` object as output, all of the `PRExplodedTime` members are set, including the nonessential members. You can also use `PR_NormalizeTime` to calculate the values of the nonessential members.

## Time Parameter Callback Functions

In some geographic locations, use of DST and the rule for determining the dates on which DST starts and ends have changed a few times. Therefore, a callback function is used to determine time zone information.

You can define your own time parameter callback functions, which must conform to the definition `PRTimeParamFn`. Two often-used callback functions of this type are provided by NSPR:

`PRTimeParamFn``
` `PR_LocalTimeParameters and PR_GMTParameters```

#### PRTimeParamFn

This type defines a callback function to calculate and return the time parameter offsets from a calendar time object in GMT.

##### Syntax

    #include <prtime.h>

    typedef PRTimeParameters (PR_CALLBACK_DECL *PRTimeParamFn)
       (const PRExplodedTime *gmt);

##### Description

The type `PRTimeParamFn` represents a callback function that, when given a time instant in GMT, returns the time zone information (offset from GMT and DST offset) at that time instant.

#### PR_LocalTimeParameters and PR_GMTParameters

Return time zone information for a clock/calendar time.

##### Syntax

    #include <prtime.h>

    PRTimeParameters PR_LocalTimeParameters (
       const PRExplodedTime *gmt);

    PRTimeParameters PR_GMTParameters (
       const PRExplodedTime *gmt);

##### Parameters

The functions each have this parameter:

gmt | A pointer to the clock/calendar time, in GMT.

##### Returns

A time parameters structure that expresses the time zone offsets at the specified time.

##### Description

These are frequently-used time parameter callback functions. You do not normally invoke these two functions directly. Rather, you pass them as arguments to `PR_ExplodeTime` and `PR_NormalizeTime`.

`PR_GMTParameters` encodes the rule of the GMT. This is a trivial function; for any input, it returns a `PRTimeParameters` structure with both fields set to 0.

`PR_LocalTimeParameters` encodes the rule of the local time zone.

## Functions

The functions that create and manipulate time and date values are:

`PR_Now``
` `PR_ExplodeTime`
`PR_ImplodeTime`
`PR_NormalizeTime`

#### PR_Now

Returns the current time.

##### Syntax

    #include <prtime.h>

    PRTime PR_Now(void);

##### Parameters

The function has no parameters.

##### Returns

The current time.

##### Description

`PR_Now` returns the current time as number of microseconds since the NSPR epoch, midnight (00:00:00) 1 January 1970 UTC.

You cannot assume that the values returned by `PR_Now` are monotonically increasing because the system clock of the computer may be reset. To obtain monotonically increasing time stamps suitable for measuring elapsed time, use `PR_IntervalNow`.

#### PR_ExplodeTime

Converts an absolute time to a clock/calendar time.

##### Syntax

    #include <prtime.h>

    void PR_ExplodeTime(
       PRTime usecs,
       PRTimeParamFn params,
       PRExplodedTime *exploded);

##### Parameters

The function has these parameters:

`usecs` | An absolute time in the `PRTime` format.
`params` | A time parameter callback function.
exploded | A pointer to a location where the converted time can be stored. This location must be preallocated by the caller.

##### Returns

Nothing

##### Description

This function converts the specified absolute time to a clock/calendar time in the specified time zone. Upon return, the location pointed to by the `exploded` parameter contains the converted time value.

#### PR_ImplodeTime

Converts a clock/calendar time to an absolute time.

##### Syntax

    #include <prtime.h>

    PRTime PR_ImplodeTime(const PRExplodedTime *exploded);

##### Parameters

The function has this parameter:

exploded | A pointer to the clock/calendar time to be converted.

##### Returns

An absolute time value.

##### Description

This function converts the specified clock/calendar time to an absolute time and returns the converted time value.

#### PR_NormalizeTime

Adjusts the fields of a clock/calendar time to their proper ranges, using a callback function.

##### Syntax

    #include <prtime.h>

    void PR_NormalizeTime (
       PR_ExplodedTime *time,
       PRTimeParamFn params);

##### Parameters

The function has these parameters:

`time` | A pointer to a clock/calendar time in the `PR_ExplodedTime` format.
`params` | A time parameter callback function.

##### Returns

Nothing

##### Description

This function adjusts the fields of the specified time structure using the specified time parameter callback function, so that they are in the proper range.

Call this function in these situations:

To normalize a time after performing arithmetic operations directly on the field values of the calendar time object. For example, if you have a `PRExplodedTime` object that represents the date 3 March 1998 and you want to say "forty days from 3 March 1998", you can simply add 40 to the `tm_mday` field and then call `PR_NormalizeTime`.

- To calculate the optional field values `tm_wday` and `tm_yday`. For example, suppose you want to compute the day of week for 3 March 1998. You can set `tm_mday` to 3, `tm_month` to 2, and `tm_year` to 1998, and all the other fields to 0, then call `PR_NormalizeTime` with `PR_GMTParameters`. On return, `tm_wday` (and `tm_yday`) are set for you.

- To convert from one time zone to another. For example, if the input argument `time` is in time zone A and the input argument `params` represents time zone B, when `PR_NormalizeTime` returns, `time` will be in time zone B.

Previous Contents Next

Last Updated May 18, 2001