info guile

7.2.5 Time

Scheme Procedure: current-time
C Function: scm_current_time (): Return the number of seconds since 1970-01-01 00:00:00 UTC, excluding leap seconds.

Scheme Procedure: gettimeofday
C Function: scm_gettimeofday (): Return a pair containing the number of seconds and microseconds since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note: whether true microsecond resolution is available depends on the operating system.

The following procedures either accept an object representing a broken down time and return a selected component, or accept an object representing a broken down time and a value and set the component to the value. The numbers in parentheses give the usual range.

Scheme Procedure: tm:sec tm
Scheme Procedure: set-tm:sec tm val: Seconds (0-59).

Scheme Procedure: tm:min tm
Scheme Procedure: set-tm:min tm val: Minutes (0-59).

Scheme Procedure: tm:hour tm
Scheme Procedure: set-tm:hour tm val: Hours (0-23).

Scheme Procedure: tm:mday tm
Scheme Procedure: set-tm:mday tm val: Day of the month (1-31).

Scheme Procedure: tm:mon tm
Scheme Procedure: set-tm:mon tm val: Month (0-11).

Scheme Procedure: tm:year tm
Scheme Procedure: set-tm:year tm val: Year (70-), the year minus 1900.

Scheme Procedure: tm:wday tm
Scheme Procedure: set-tm:wday tm val: Day of the week (0-6) with Sunday represented as 0.

Scheme Procedure: tm:yday tm
Scheme Procedure: set-tm:yday tm val: Day of the year (0-364, 365 in leap years).

Scheme Procedure: tm:isdst tm
Scheme Procedure: set-tm:isdst tm val: Daylight saving indicator (0 for “no”, greater than 0 for “yes”, less than 0 for “unknown”).

Scheme Procedure: tm:gmtoff tm

Scheme Procedure: set-tm:gmtoff tm val

Time zone offset in seconds west of UTC (-46800 to 43200). For example on East coast USA (zone ‘EST+5’) this would be 18000 (ie. 5*60*60) in winter, or 14400 (ie. 4*60*60) during daylight savings.

Note tm:gmtoff is not the same as tm_gmtoff in the C tm structure. tm_gmtoff is seconds east and hence the negative of the value here.

Scheme Procedure: tm:zone tm
Scheme Procedure: set-tm:zone tm val: Time zone label (a string), not necessarily unique.

Scheme Procedure: localtime time [zone]
C Function: scm_localtime (time, zone): Return an object representing the broken down components of time, an integer like the one returned by current-time. The time zone for the calculation is optionally specified by zone (a string), otherwise the TZ environment variable or the system default is used.

Scheme Procedure: gmtime time
C Function: scm_gmtime (time): Return an object representing the broken down components of time, an integer like the one returned by current-time. The values are calculated for UTC.

Scheme Procedure: mktime sbd-time [zone]

C Function: scm_mktime (sbd_time, zone)

For a broken down time object sbd-time, return a pair the car of which is an integer time like current-time, and the cdr of which is a new broken down time with normalized fields.

zone is a timezone string, or the default is the TZ environment variable or the system default (see Specifying the Time Zone with TZ in GNU C Library Reference Manual). sbd-time is taken to be in that zone.

The following fields of sbd-time are used: tm:year, tm:mon, tm:mday, tm:hour, tm:min, tm:sec, tm:isdst. The values can be outside their usual ranges. For example tm:hour normally goes up to 23, but a value say 33 would mean 9 the following day.

tm:isdst in sbd-time says whether the time given is with daylight savings or not. This is ignored if zone doesn’t have any daylight savings adjustment amount.

The broken down time in the return normalizes the values of sbd-time by bringing them into their usual ranges, and using the actual daylight savings rule for that time in zone (which may differ from what sbd-time had). The easiest way to think of this is that sbd-time plus zone converts to the integer UTC time, then a localtime is applied to get the normal presentation of that time, in zone.

Scheme Procedure: tzset
C Function: scm_tzset (): Initialize the timezone from the TZ environment variable or the system default. It’s not usually necessary to call this procedure since it’s done automatically by other procedures that depend on the timezone.

Scheme Procedure: strftime format tm

C Function: scm_strftime (format, tm)

Return a string which is broken-down time structure tm formatted according to the given format string.

format contains field specifications introduced by a ‘%’ character. See Formatting Calendar Time in The GNU C Library Reference Manual, or ‘man 3 strftime’, for the available formatting.

(strftime "%c" (localtime (current-time)))
⇒ "Mon Mar 11 20:17:43 2002"

If setlocale has been called (see section Locales), month and day names are from the current locale and in the locale character set.

Scheme Procedure: strptime format string
C Function: scm_strptime (format, string): Performs the reverse action to strftime, parsing string according to the specification supplied in format. The interpretation of month and day names is dependent on the current locale. The value returned is a pair. The CAR has an object with time components in the form returned by localtime or gmtime, but the time zone components are not usefully set. The CDR reports the number of characters from string which were used for the conversion.

Variable: internal-time-units-per-second: The value of this variable is the number of time units per second reported by the following procedures.

Scheme Procedure: times

C Function: scm_times ()

Return an object with information about real and processor time. The following procedures accept such an object as an argument and return a selected component:

Scheme Procedure: tms:clock tms: The current real time, expressed as time units relative to an arbitrary base.

Scheme Procedure: tms:utime tms: The CPU time units used by the calling process.

Scheme Procedure: tms:stime tms: The CPU time units used by the system on behalf of the calling process.

Scheme Procedure: tms:cutime tms: The CPU time units used by terminated child processes of the calling process, whose status has been collected (e.g., using waitpid).

Scheme Procedure: tms:cstime tms: Similarly, the CPU times units used by the system on behalf of terminated child processes.

Scheme Procedure: get-internal-real-time
C Function: scm_get_internal_real_time (): Return the number of time units since the interpreter was started.

Scheme Procedure: get-internal-run-time
C Function: scm_get_internal_run_time (): Return the number of time units of processor time used by the interpreter. Both system and user time are included but subprocesses are not.

This document was generated on April 20, 2013 using texi2html 5.0.