Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

21    time.h

Palm OS® Protein C/C++ Compiler Language & Library Reference

Palm OS® Developer Suite

The <time.h> header defines several Palm OS® specific functions useful for reading and converting the current time and date.

Constants ^TOP^

TZNAME_MAX ^TOP^

Purpose

Defines the maximum length of a time zone identifier string.

Declared In

posix/sys/time.h

Constants

#define TZNAME_MAX 32

Functions and Macros ^TOP^

getcountrycode Function ^TOP^

Purpose

Gets the two-byte country code for the specified time zone.

Declared In

posix/sys/time.h

Prototype

status_t getcountrycode (
   const char *tzname,
   char *buf,
   size_t bufsize
)

Parameters

tzname
The time zone.
buf
The buffer.
bufsize
The size of the buffer.

Returns

Returns P_OK upon successful completion; otherwise it returns P_ERROR.

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

getgmtoffset Function ^TOP^

Purpose

Gets the difference in seconds between Greenwich Mean Time (GMT) and local standard time.

Declared In

posix/sys/time.h

Prototype

int32_t getgmtoffset (
   const char *tznanme
)

Parameters

tzname
The time zone.

Returns

Returns the current GMT offset, which takes into account daylight saving time. This difference is positive for time zones West of Greenwich and negative for zones East of Greenwich.

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

gettimezone Function ^TOP^

Purpose

Copies the current system time zone name into buf.

Declared In

posix/sys/time.h

Prototype

ssize_t gettimezone (
   char *buf,
   size_t bufsize
)

Parameters

buf
The buffer.
bufsize
The size of the buffer.

Returns

Returns the number of bytes copied into buf upon successful completion; otherwise it returns P_ERROR.

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

See Also

hastimezone(), settimezone()

hastimezone Function ^TOP^

Purpose

Determines if the system has the specified timezone. That is, if a timezone database is installed for the specified timezone.

Declared In

posix/sys/time.h

Prototype

int hastimezone (
   const char *tzname
)

Parameters

tzname
The time zone.

Returns

Returns P_OK upon successful completion; otherwise it returns P_ERROR.

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

See Also

gettimezone(), settimezone()

localtime_tz Function ^TOP^

Purpose

Converts the specified UTC time in the time zone to a broken-down time.

Declared In

posix/sys/time.h

Prototype

void localtime_tz (
   const time_t *timer,
   const char *tzname,
   struct tm *result
)

Parameters

timer
The calendar time.
tzname
The time zone.
result
A tm structure.

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

mktime_tz Function ^TOP^

Purpose

Converts a specified broken-down time in the time zone to UTC time. If the tm_isdst member of the tm struct is negative, this function tries to determine if the specified time zone is currently in daylight saving time.

Declared In

posix/sys/time.h

Prototype

time_t mktime_tz (
   struct tm *tm,
   const char *tzname
)

Parameters

tm
A tm structure.
tzname
The time zone.

Returns

Returns the UTC time.

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

palm_seconds_to_time_t Function ^TOP^

Purpose

Takes as input the number of seconds since 1/1/1904 (old Palm epoch) and returns the number of seconds since 1/1/1970 (Unix epoch).

Declared In

posix/sys/time.h

Prototype

time_t palm_seconds_to_time_t (
   uint32_t seconds
)

Parameters

seconds
The number of seconds.

Returns

Returns the number of seconds since 1/1/1970 (Unix epoch).

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

See Also

time_t_to_palm_seconds()

settime Function ^TOP^

Purpose

Sets the system time to the specified time.

Declared In

posix/sys/time.h

Prototype

status_t settime (
   time_t time
)

Parameters

time
The system time.

Returns

Returns P_OK upon successful completion.

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

settimezone Function ^TOP^

Purpose

Sets the system's time zone.

Declared In

posix/sys/time.h

Prototype

status_t settimezone (
   const char *tzname
)

Parameters

tzname
The time zone.

Returns

Returns P_OK upon successful completion; otherwise it returns P_ERROR.

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

See Also

gettimezone(), hastimezone()

system_real_time Function ^TOP^

Purpose

Gets the value of the real time clock in nanoseconds.

Declared In

posix/sys/time.h

Prototype

nsecs_t system_real_time (
   void
)

Returns

Returns the value of the real time clock in nanoseconds.

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

system_time Function ^TOP^

Purpose

Gets the value of the run time clock in nanoseconds.

Declared In

posix/sys/time.h

Prototype

nsecs_t system_time (
   void
)

Returns

Returns the value of the run time clock in nanoseconds.

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

time_t_to_palm_seconds Function ^TOP^

Purpose

Takes as input the number of seconds since 1/1/1970 (Unix epoch) and returns the number of seconds since 1/1/1904 (old Palm epoch).

Declared In

posix/sys/time.h

Prototype

uint32_t time_t_to_palm_seconds (
   time_t seconds
)

Parameters

seconds
The number of seconds.

Returns

Returns the number of seconds since 1/1/1904 (old Palm epoch).

Compatibility

This function is a Palm OS extension (not present in C99 or Unix).

See Also

palm_seconds_to_time_t()