ADC Home > Reference Library > Reference > Internationalization > Carbon > Date, Time, and Measurement Utilities Reference >

< Previous PageNext Page > Hide TOC

Deprecated Date, Time, and Measurement Utilities Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.3

DateString

Converts a date in the standard date-time representation into a Pascal string, making use of the date formatting information in the specified resource. (Deprecated in Mac OS X v10.3. Use CFDateFormatterCreateStringWithDate instead.)

void DateString (
   SInt32 dateTime,
   DateForm longFlag,
   Str255 result,
   Handle intlHandle
);

Parameters
dateTime

The date-time value in the representation returned by the GetDateTime function. The numeric representation used in these functions is the standard date-time representation: a 32-bit integer value that is returned by the GetDateTime function. This is a long integer value that represents the number of seconds between midnight, January 1, 1904, and the time at which GetDateTime was called.

longFlag

A flag that indicates the desired format for the date string. This is one of the three values defined as the DateForm type.

The string produced by DateString is in one of three standard date formats used on the Macintosh, depending on which of the three DateForm values that you specify for the longFlag parameter: shortDate, abbrevDate, or longDate. The information in the supplied resource defines how month and day names are written and provides for calendars with more than 7 days and more than 12 months.

For the Roman script system’s resource, the date January 31, 1992, produces the following three strings: “1/31/92“, “Fri, Jan 31, 1992“, and “Friday, January 31, 1992“(for DateForm values shortDate, abbrevDate, and longDate, respectively).

result

On output, contains the string representation of the date in the format indicated by the longFlag parameter.

intlHandle

A handle to a numeric-format or a long-date-format resource that specifies date formatting information for use in the conversion. If you specify NULL as the value of the resource handle parameter, DateString uses information from the current script. The numeric-format ('itl0') resource specifies the short date formats and the long-date-format ('itl1') resource specifies the long date formats.

DateString formats its data according to the information in the specified numeric-format resource (for short date formats) or long-date-format resource (for long date formats). If you specify shortDate, the intlHandle value should be the handle to a numeric-format resource; if you specify abbrevDate or longDate, it should be the handle to a long-date-format resource.

Availability
Declared In
DateTimeUtils.h

DateToSeconds

Converts a date and time to a number of seconds elapsed since midnight, January 1, 1904. (Deprecated in Mac OS X v10.3. Use the CFCalendarRef data type and the functions that operate on it instead.)

void DateToSeconds (
   const DateTimeRec *d,
   unsigned long *secs
);

Parameters
d

The date-time structure containing the date and time to convert.

secs

On return, the number of seconds elapsed between midnight, January 1, 1904, and the time specified in the d parameter. For example, specifying a date and time of 11:33 A.M. on January 1, 1904 results in 41580 being returned in this parameter.

Special Considerations

For information on using the CFCalendarRef data type, see Data Formatting Guide for Core Foundation and CFCalendar Reference.

Availability
Declared In
DateTimeUtils.h

GetDateTime

Obtains the current date-time information, expressed as the number of seconds elapsed since midnight, January 1, 1904. (Deprecated in Mac OS X v10.3. Use CFAbsoluteTimeGetCurrent instead.)

void GetDateTime (
   unsigned long *secs
);

Parameters
secs

On return, the number of seconds elapsed since midnight, January 1, 1904.

Discussion

The low-memory copy of the date and time information is also accessible through the global variable Time.

If an application disables interrupts for longer than a second, the date-time information returned by the GetDateTime function might not be exact. The GetDateTime function is intended to provide fairly accurate time information, but not scientifically precise data.

Availability
Declared In
DateTimeUtils.h

InitDateCache

Initializes the date cache structure, which is used to store data for use by the StringToDate and StringToTime functions. (Deprecated in Mac OS X v10.3. There is no replacement.)

OSErr InitDateCache (
   DateCachePtr theCache
);

Parameters
theCache

A pointer to a date cache structure. This parameter can be a local variable, a pointer, or a locked handle.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

You must call InitDateCache to initialize the date cache structure before using either the StringToDate or StringToTime functions. You must pass a pointer to a date cache structure. You have to declare the structure as a variable or allocate it in the heap.

If you are writing an application that allows the use of global variables, you can make your date cache structure a global variable and initialize it once, when you perform other global initialization.

InitDateCache calls the GetResource and LoadResource functions and it can also return the error codes they produce.

Special Considerations

You no longer need to initialize the data cache in Mac OS X.

Availability
Declared In
DateTimeUtils.h

LongDateString

Converts a date that is specified as a LongDateTime value into a Pascal string, making use of the date formatting information in the specified resource. (Deprecated in Mac OS X v10.3. Use CFDateFormatterCreateStringWithDate instead.)

void LongDateString (
   const LongDateTime *dateTime,
   DateForm longFlag,
   Str255 result,
   Handle intlHandle
);

Parameters
dateTime

A pointer to a 64-bit, signed representation of the number of seconds since Jan. 1, 1904. This allows coverage of a much longer span of time (plus or minus approximately 30,000 years) than the standard, 32-bit representation.

longFlag

A flag that indicates the desired format for the date string. This is one of the three values defined as the DateForm type.

The string produced by LongDateString is in one of three standard date formats used on the Macintosh, depending on which of the three DateForm values that you specify for the longFlag parameter: shortDate, abbrevDate, or longDate. The information in the supplied resource defines how month and day names are written and provides for calendars with more than 7 days and more than 12 months.

For the U.S. resource, the date January 31, 1992, produces the following three strings: “1/31/92“, “Fri, Jan 31, 1992“, and “Friday, January 31, 1992“(for DateForm values shortDate, abbrevDate, and longDate, respectively).

result

On output, contains the string representation of the date in the format indicated by the longFlag parameter.

intlHandle

A handle to a numeric-format or long-date-format resource that specifies date formatting information for use in the conversion. If you specify NULL as the value of the resource handle parameter, LongDateString uses information from the current script. The numeric-format ('itl0') resource specifies the short date formats and the long-date-format ('itl1') resource specifies the long date formats.

If you specify shortDate in the longFlag parameter, the intlHandle value should be the handle to a numeric-format resource; if you specify abbrevDate or longDate, it should be the handle to a long-date-format resource.

Discussion

You can use the LongSecondsToDate and LongDateToSeconds functions to convert between the LongDateRec (as produced by the StringToDate function) and LongDateTime data types.

Availability
Declared In
DateTimeUtils.h

LongDateToSeconds

Converts a date and time to the number of seconds elapsed since midnight, January 1, 1904. (Deprecated in Mac OS X v10.3. Use the CFCalendarRef data type and the functions that operate on it instead.)

void LongDateToSeconds (
   const LongDateRec *lDate,
   LongDateTime *lSecs
);

Parameters
lDate

The long date-time structure containing the date and time to convert.

lSecs

On return, the number of seconds elapsed since midnight, January 1, 1904, and the time specified in the lDate parameter. The number of seconds are returned as a long date-time value.

Special Considerations

For information on using the CFCalendarRef data type, see Data Formatting Guide for Core Foundation and CFCalendar Reference.

Availability
Declared In
DateTimeUtils.h

LongSecondsToDate

Converts the number of seconds elapsed since midnight, January 1, 1904 to a date and time. (Deprecated in Mac OS X v10.3. Use the CFCalendarRef data type and the functions that operate on it instead.)

void LongSecondsToDate (
   const LongDateTime *lSecs,
   LongDateRec *lDate
);

Parameters
lSecs

The number of seconds elapsed since midnight, January 1, 1904.

lDate

On return, the fields of the long date-time structure that contain the date and time corresponding to the value indicated in the lSecs parameter. For example, specifying the number of seconds 41580 results in the date and time 11:33 A.M. on January 1, 1904 being returned in this parameter.

Special Considerations

For information on using the CFCalendarRef data type, see Data Formatting Guide for Core Foundation and CFCalendar Reference.

Availability
Declared In
DateTimeUtils.h

LongTimeString

Converts a time that is specified as a LongDateTime value into a Pascal string, making use of the time formatting information in the specified resource. (Deprecated in Mac OS X v10.3. Use CFDateFormatterCreateStringWithDate instead.)

void LongTimeString (
   const LongDateTime *dateTime,
   Boolean wantSeconds,
   Str255 result,
   Handle intlHandle
);

Parameters
dateTime

A pointer to a 64-bit, signed representation of the number of seconds since Jan. 1, 1904. This allows coverage of a much longer span of time (plus or minus approximately 30,000 years) than the standard, 32-bit representation.

wantSeconds

A flag that indicates whether the seconds are to be included in the resulting string. LongTimeString produces a string that includes the seconds if you set this parameter to TRUE.

result

On output, contains the string representation of the time.

intlHandle

A handle to a numeric-format ('itl0') resource that specifies time formatting information for use in the conversion. If you specify NULL as the value of the resource handle parameter, LongTimeString uses information from the current script.

The numeric-format resource specifies whether or not to use leading zeros for the time values, whether to use a 12- or 24-hour time cycle, and how to specify morning or evening if a 12-hour time cycle is used.

Discussion

You can use the LongSecondsToDate and LongDateToSeconds functions to convert between the LongDateRec (as produced by the StringToTime function) and LongDateTime data types.

Availability
Declared In
DateTimeUtils.h

ReadDateTime

Reads time information from the system. (Deprecated in Mac OS X v10.3. Use CFAbsoluteTimeGetCurrent instead.)

OSErr ReadDateTime (
   unsigned long *time
);

Parameters
time

On return, the current time expressed as the number of seconds elapsed since midnight, January 1, 1904.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.” If the clock chip cannot be read, ReadDateTime returns the clkRdErr result code. The operation might fail if the clock chip is damaged. Otherwise, the function returns the noErr result code.

Availability
Declared In
DateTimeUtils.h

SecondsToDate

Converts a number of seconds elapsed since midnight, January 1, 1904 to a date and time. (Deprecated in Mac OS X v10.3. Use the CFCalendarRef data type and the functions that operate on it instead.)

void SecondsToDate (
   unsigned long secs,
   DateTimeRec *d
);

Parameters
secs

The number of seconds elapsed since midnight, January 1, 1904.

d

On return, the fields of the date-time structure that contain the date and time corresponding to the value indicated in the s parameter.

Special Considerations

For information on using the CFCalendarRef data type, see Data Formatting Guide for Core Foundation and CFCalendar Reference.

Availability
Declared In
DateTimeUtils.h

SetDateTime

Changes the date-time information stored by the system to the specified value, expressed as the number of seconds elapsed since midnight, January 1, 1904. (Deprecated in Mac OS X v10.3. There is no replacement.)

OSErr SetDateTime (
   unsigned long time
);

Parameters
time

The number of seconds elapsed since midnight, January 1, 1904; this value is written to the system.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.” The SetDateTime function attempts to verify the value written by reading it back in and comparing it to the value in the low-memory copy. If a problem occurs, the SetDateTime function returns either the clkRdErr result code, because the clock chip could not be read, or the clkWrErr result code, because the time written to the clock chip could not be verified. Otherwise, the function returns the noErr result code.

Special Considerations

Only the root user can set the time in Mac OS X.

Availability
Declared In
DateTimeUtils.h

SetTime

Changes the date-time information in the system to the specified value, expressed as a date and time. (Deprecated in Mac OS X v10.3. There is no replacement.)

void SetTime (
   const DateTimeRec *d
);

Parameters
d

The date and time to which to set in the system.

Discussion

The SetTime function first converts the date and time to the number of seconds elapsed since midnight, January 1, 1904 by calling the DateToSeconds function. It then writes these seconds to the system and to the system global variable Time by calling the SetDateTime function.

The SetTime function does not return a result code. If you need to know whether an attempt to change the date and time information in the system is successful, you must use the SetDateTime function.

As an alternative to using the SetTime procedure, you can use the DateToSeconds and SetDateTime functions.

Special Considerations

Only the root user can set the time in Mac OS X.

Availability
Declared In
DateTimeUtils.h

StringToDate

Parses a string for a date and converts the date information into values in a date-time structure. (Deprecated in Mac OS X v10.3. Use CFDateFormatterCreateDateFromString instead.)

StringToDateStatus StringToDate (
   Ptr textPtr,
   SInt32 textLen,
   DateCachePtr theCache,
   SInt32 *lengthUsed,
   LongDateRec *dateTime
);

Parameters
textPtr

A pointer to the text string to be parsed. StringToDate expects a date specification, in a format defined by the current script, at the beginning of the string.

textLen

The number of bytes in the text string.

theCache

A pointer to the date cache structure initialized by the InitDateCache function with data that is used during the conversion process.

lengthUsed

On output, contains a pointer to the number of bytes of the string that were parsed for the date. Use this value to compute the starting location of the text that you can pass to StringToTime. Alternatively, you can use them in reverse order.

dateTime

On output, a pointer to the LongDateRec structure, which contains the year, month, day, and day of the week parsed for the date.

Return Value

A set of bit values that indicate confidence levels, with higher numbers indicating low confidence in how closely the input string matched what the function expected. For example, specifying a date with nonstandard separators may work, but it returns a message indicating that the separator was not standard. See the description of the StringToDateStatus data type.

Discussion

StringToDate parses the text string until it has finished finding all date information or until it has examined the number of bytes specified by textLen.

Note that StringToDate fills in only the year, month, day, and day of the week; StringToTime fills in the hour, minute, and second. You can use these two functions sequentially to fill in all of the values in a LongDateRec structure.

When one of the date components is missing, such as the year, the current date value is used as a default.

Availability
Declared In
DateTimeUtils.h

StringToTime

Parses a string for a time specification and converts the date information into values in a date-time structure. (Deprecated in Mac OS X v10.3. Use CFDateFormatterCreateDateFromString instead.)

StringToDateStatus StringToTime (
   Ptr textPtr,
   SInt32 textLen,
   DateCachePtr theCache,
   SInt32 *lengthUsed,
   LongDateRec *dateTime
);

Parameters
textPtr

A pointer to the text string to be parsed. At the beginning of the string, StringToTime expects a time specification in a format defined by the current script.

textLen

The number of bytes in the text string.

theCache

A pointer to the date cache structure initialized by the InitDateCache function with data that is used during the conversion process.

lengthUsed

On output, contains a pointer to the length, in bytes, of the string that was parsed for the time.

dateTime

On output, a pointer to the LongDateRec structure, which contains the hour, minute, and second values that were parsed for the time.

Return Value

StringToTime returns a status value that indicates the confidence level for the success of the conversion. This is the same status value indicator type as does StringToDate: a set of bit values that indicate confidence levels, with higher numbers indicating low confidence in how closely the input string matched what the function expected. See the description of the StringToDateStatus data type.

Discussion

StringToTime parses the string until it has finished finding all time information or until it has examined the number of bytes specified by textLen.

Note that StringToTime fills in only the hour, minute, and second; StringToDate fills in the year, month, day, and day of the week. You can use these two functions sequentially to fill in all of the values in a LongDateRec structure.

Availability
Declared In
DateTimeUtils.h

TimeString

Converts a time in the standard date-time representation into a string, making use of the time formatting information in the specified resource. (Deprecated in Mac OS X v10.3. Use CFDateFormatterCreateStringWithDate instead.)

void TimeString (
   SInt32 dateTime,
   Boolean wantSeconds,
   Str255 result,
   Handle intlHandle
);

Parameters
dateTime

The date-time value in the representation returned by the Operating System function GetDateTime. The numeric representation used in these functions is the standard date-time representation: a 32-bit integer value that is returned by the GetDateTime function. This is a long integer value that represents the number of seconds between midnight, January 1, 1904, and the time at which GetDateTime was called.

wantSeconds

A flag that indicates whether the seconds are to be included in the resulting string.

result

On output, contains the string representation of the time.

intlHandle

A handle to a numeric-format ('itl0') resource that specifies time formatting information for use in the conversion. If you specify NULL as the value of the resource handle parameter, TimeString uses information from the current script.

The numeric-format resource specifies whether or not to use leading zeros for the time values, whether to use a 12- or 24-hour time cycle, and how to specify morning or evening if a 12-hour time cycle is used.

Availability
Declared In
DateTimeUtils.h

ToggleDate

Modifies a date and time, by modifying one specific component of a date and time (day, hour, minute, seconds, day of week, and so on). (Deprecated in Mac OS X v10.3. Use the CFCalendarRef data type and the functions that operate on it instead.)

ToggleResults ToggleDate (
   LongDateTime *lSecs,
   LongDateField field,
   DateDelta delta,
   short ch,
   const TogglePB *params
);

Parameters
lSecs

The date-time information to modify, expressed as the number of seconds elapsed since midnight, January 1, 1904.

field

The name of the field in the date-time structure you want modify. Use one of the Long Date Mask Constants for the value of this parameter.

delta

A signed byte specifying the action you want to perform on the value specified in the field parameter. Set delta to 1, to increase the value in the field by 1. Set delta to -1, to decrease the value of the field by 1. Set delta to 0. If you want to set the value of the field explicitly; pass the new value through the ch field.

ch

If the value in the delta field is 0, the value of the field in the date-time structure (specified by the field parameter) is set to the value in the ch parameter. If the value in the delta field is not equal to 0, the value in the ch parameter is ignored.

params

The user-defined settings of the toggle parameter block settings.

Return Value

See the description of the ToggleResults data type.

Discussion

The relevant fields of the toggle parameter block are:

You must supply values for all input parameters.

The ToggleDate function first converts the number of seconds and makes each component of the date and time available through a long date-time structure. The ToggleDate function then modifies the value of the field, specified by the field parameter. If the value in the delta field is greater than 0, the value of the field increases by 1; if the value in the delta field is less than 0, the value of the field decreases by 1; and if the value of delta is 0, the value of the field is explicitly set to the value specified in the ch field. After the ToggleDate function modifies the field, it calls the ValidDate function. The ValidDate function checks the long date-time structure for correctness. If any of the structure fields are invalid, the ValidDate function returns a LongDateField value corresponding to the field in error. Otherwise, it returns the result code for validDateFields. Note that ValidDate reports only the least significant erroneous field.

After the ToggleDate function checks the validity of the modified field, it converts the modified date and time back into a number of seconds and returns these seconds in the lSecs parameter.

The ToggleDate function was previously available with the Script Manager.

For more information on the LongDateRec structure, see LongDateRec. The toggle parameter block structure is described in TogglePB.

For more information about the GetIntlResource function, see the Script Manager. For details on the UppercaseText function, see Text Utilities.

Special Considerations

For information on using the CFCalendarRef data type, see Data Formatting Guide for Core Foundation and CFCalendar Reference.

Availability
Declared In
DateTimeUtils.h

ValidDate

Verifies specific date and time values in a long date-time structure. (Deprecated in Mac OS X v10.3. Use the CFCalendarRef data type and the functions that operate on it instead.)

short ValidDate (
   const LongDateRec *vDate,
   long flags,
   LongDateTime *newSecs
);

Parameters
vDate

The long date-time structure whose fields you want to verify.

flags

The fields that you want to verify in the long date-time structure. For a description of the values you can use in this parameter, see Long Date Mask Constants.

newSecs

The date-time information, passed by the ToggleDate function, that you want to verify.

Return Value

If any of the specified fields contain invalid values, the ValidDate function returns a LongDateField value indicating the field in error. Otherwise, it returns the constant validDateFields. ValidDate reports only the least significant erroneous field.

Discussion

For more information on the LongDateRec structure, see LongDateRec. The toggle parameter block structure is described in TogglePB.

Special Considerations

For information on using the CFCalendarRef data type, see Data Formatting Guide for Core Foundation and CFCalendar Reference.

Availability
Declared In
DateTimeUtils.h

Deprecated in Mac OS X v10.4

ConvertLocalTimeToUTC

Converts local time to UTC. (Deprecated in Mac OS X v10.4. Use CFTimeZoneGetSecondsFromGMT instead.)

OSStatus ConvertLocalTimeToUTC (
   UInt32 localSeconds,
   UInt32 *utcSeconds
);

Parameters
localSeconds

A value of type UInt32 containing the local time.

utcSeconds

A pointer to a value of type UInt32. On return, this points to the UTC value corresponding to the given time in localSeconds.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

Given a local time in localSeconds, the function will place the corresponding UTC value in utcSeconds. This function returns noErr if the conversion is successful. Otherwise, it may return kUTCUnderflowErr or kUTCOverflowErr.

Special Considerations

For information on using CFTimeZoneGetSecondsFromGMT, see Dates and Times Programming Guide for Core Foundation andCFTimeZone Reference.

Availability
Declared In
UTCUtils.h

ConvertLocalToUTCDateTime

Converts local date and time to UTC date and time. (Deprecated in Mac OS X v10.4. Use CFTimeZoneGetSecondsFromGMT instead.)

OSStatus ConvertLocalToUTCDateTime (
   const LocalDateTime *localDateTime,
   UTCDateTime *utcDateTime
);

Parameters
localDateTime

A value of type LocalDateTime containing the local date and time.

utcDateTime

A pointer to a value of type UTCDateTime. On return, this points to the UTC value corresponding to the given date and time in localDateTime.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

Given a local date and time in the localDateTime parameter, this function places the corresponding UTC value in utcDateTime. This function returns noErr if the conversion is successful. Otherwise, it may return kUTCUnderflowErr, kUTCOverflowErr, or paramErr if utcDateTime is NULL.

Availability
Declared In
UTCUtils.h

ConvertUTCToLocalDateTime

Converts UTC date and time to local date and time. (Deprecated in Mac OS X v10.4. Use CFTimeZoneGetSecondsFromGMT instead.)

OSStatus ConvertUTCToLocalDateTime (
   const UTCDateTime *utcDateTime,
   LocalDateTime *localDateTime
);

Parameters
utcDateTime

A value of type UTCDateTime specifying the UTC date and time.

localDateTime

A pointer to a value of type LocalDateTime. On return, this points to the local value corresponding to the given date and time in utcDateTime.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

Given a UTC date and time in utcDateTime, this function places the corresponding local value in localDateTime. This function returns noErr if the conversion is successful. Otherwise, it may return kUTCUnderflowErr, kUTCOverflowErr, or paramErr if localDateTime is NULL.

Availability
Declared In
UTCUtils.h

ConvertUTCToLocalTime

Converts UTC time to local time. (Deprecated in Mac OS X v10.4. Use CFTimeZoneGetSecondsFromGMT instead.)

OSStatus ConvertUTCToLocalTime (
   UInt32 utcSeconds,
   UInt32 *localSeconds
);

Parameters
utcSeconds

A value of type UInt32 specifying UTC time in seconds.

localSeconds

A pointer to a value of type UInt32. On return, this points to the local time corresponding to the UTC time specified in utcSeconds.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

Given a UTC time in utcSeconds this function places the corresponding local value in localSeconds. This function returns noErr if the conversion is successful. Otherwise, it may return kUTCUnderflowErr or kUTCOverflowErr.

Availability
Declared In
UTCUtils.h

GetLocalDateTime

Gets the local date and time. (Deprecated in Mac OS X v10.4. Use CFAbsoluteTimeGetCurrent and CFTimeZoneGetSecondsFromGMT instead.)

OSStatus GetLocalDateTime (
   LocalDateTime *localDateTime,
   OptionBits options
);

Parameters
localDateTime

A pointer to a value of type LocalDateTime. On return, the value this parameter points to is the current local date and time.

options

A value of type OptionBits. Pass kUTCDefaultOptions for the default behavior.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

This API returns the current date and time in localTime. Otherwise, it is set to 0. Use kUTCDefaultOptions in the options parameter for default behavior. Different behavior may be specified through this parameter in the future. If the operation is successful noErr is returned. If a NULL pointer is passed in the localDateTime parameter, paramErr is returned.

Availability
Declared In
UTCUtils.h

GetUTCDateTime

Gets the UTC date and time. (Deprecated in Mac OS X v10.4. Use CFAbsoluteTimeGetCurrent instead.)

OSStatus GetUTCDateTime (
   UTCDateTime *utcDateTime,
   OptionBits options
);

Parameters
utcDateTime

A pointer to a value of type UTCDateTime. On return, the value this parameter points to is the current UTC date and time.

options

A value of type OptionBits. Pass kUTCDefaultOptions for the default behavior.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

This API returns the current date and time as UTC in utcDateTime. Otherwise, it is set to 0. Use kUTCDefaultOptions in the options for default behavior. Different behavior may be specified through this parameter in the future. If the operation is successful noErr is returned. If a NULL pointer is passed in utcDateTime, paramErr is returned.

Availability
Declared In
UTCUtils.h

SetLocalDateTime

Sets the local date and time. (Deprecated in Mac OS X v10.4. There is no replacement.)

OSStatus SetLocalDateTime (
   const LocalDateTime *localDateTime,
   OptionBits options
);

Parameters
localDateTime

A pointer to a value of type LocalDateTime specifying the current local date and time.

options

A value of type OptionBits. Pass kUTCDefaultOptions for the default behavior.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

Use this call to set the clock to the date and time passed in the localDateTime parameter. Use kUTCDefaultOptions in the options for default behavior. Different behavior may be specified through this parameter in the future. If successful noErr is returned. Other errors include kIllegalClockValueErr, paramErr if localDateTime is NULL, or clkWrErr due to a failed attempt to write the value to the system.

Special Considerations

Only the root user can set the time in Mac OS X.

Availability
Declared In
UTCUtils.h

SetUTCDateTime

Sets the UTC date and time. (Deprecated in Mac OS X v10.4. Use settimeofday(2) instead.)

OSStatus SetUTCDateTime (
   const UTCDateTime *utcDateTime,
   OptionBits options
);

Parameters
utcDateTime

A pointer to a value of type UTCDateTime specifying the current UTC date and time.

options

A value of type OptionBits. Pass kUTCDefaultOptions for the default behavior.

Return Value

A result code. See “Date, Time, and Measurement Utilities Result Codes.”

Discussion

Use this call to set the clock to the date and time passed in the utcDateTime parameter. Use kUTCDefaultOptions in the options for default behavior. Different behavior may be specified through this parameter in the future. If successful noErr is returned. Other errors include kIllegalClockValueErr, kUTCUnderflowErr, kUTCOverflowErr, and paramErr if NULL is passed for utcDateTime. It may also return clkWrErr due to a failed attempt to write the value to the system.

Special Considerations

Only the root user can set the time in Mac OS X.

Availability
Declared In
UTCUtils.h

< Previous PageNext Page > Hide TOC

© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-09-29)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.