You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

NSPR Reference

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 9 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 32400 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, PRExplodedTimePRTimeParameters 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.