void et2utc_c ( SpiceDouble et,
ConstSpiceChar * format,
SpiceChar * utcstr )
Convert an input time from ephemeris seconds past J2000
to Calendar, Day-of-Year, or Julian Date format, UTC.
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
et I Input epoch, given in ephemeris seconds past J2000.
format I Format of output epoch.
prec I Digits of precision in fractional seconds or days.
lenout I The length of the output string plus 1.
utcstr O Output time string, UTC.
et is the input epoch, ephemeris seconds past J2000.
format is the format of the output time string. It may be
any of the following:
"C" Calendar format, UTC.
"D" Day-of-Year format, UTC.
"J" Julian Date format, UTC.
"ISOC" ISO Calendar format, UTC.
"ISOD" ISO Day-of-Year format, UTC.
prec is the number of digits of precision to which
fractional seconds (for Calendar and Day-of-Year
formats) or days (for Julian Date format) are to
be computed. If PREC is zero or smaller, no decimal
point is appended to the output string. If PREC is
greater than 14, it is treated as 14.
lenout The allowed length of the output string. This length
must large enough to hold the output string plus the
null terminator. If the output string is expected to
have x characters, lenout must be x + 1.
utcstr is the output time string equivalent to the input
epoch, in the specified format. Some examples are
"C" "1986 APR 12 16:31:09.814"
"D" "1986-102 // 16:31:12.814"
"J" "JD 2446533.18834276"
If an error occurs, utcstr is not changed.
Fractional seconds, or for Julian dates, fractional
days, are rounded to the precision level specified
by the input argument `prec'.
utcstr should be declared to be at least
20 + prec characters in length to ensure
sufficient room to hold calendar strings
for modern epochs. For epochs prior to
1000 A.D. at least 24 + prec characters in
length are required to hold the output
For epochs prior to 1000 A.D. Jan 1 calendar
and day of year formats are returned with the
era (A.D. or B.C.) attached to the year. For
"877 A.D. MAR 17 13:29:11.829"
"471 B.C. Jan 01 12:00:00.000"
"471 B.C. 001 // 12:00:00.000"
ISO formats do not support the inclusion of
an era. For years prior to 1 A.D. an error
will be signaled if ISO format has been requested.
1) If the format for the output string is not recognized, the
error SPICE(INVALIDTIMEFORMAT) is signaled.
2) If prec is less than or equal to zero, it is treated as
zero. If prec is greater than 14, it is treated as 14.
3) If one of the ISO formats is specified (ISOC or ISOD) but
the year corresponding to ET is prior to 1 A.D. on the
Gregorian Calendar, the error SPICE(YEAROUTOFRANGE) will
4) Epochs prior to 15 Oct, 1582 on the Gregorian calendar (the
calendar commonly used in western societies) are returned in the
"extended" Gregorian Calendar. To convert epochs to the Julian
calendar see the header of the function gr2jul_ in the file
5) This routine does not attempt to account for variations
in the length of the second that were in effect prior
to Jan 1, 1972. For days prior to that date, we assume
there are exactly 86400 ephemeris seconds. Consequently
the UTC gregorian calendar strings produced for epochs
prior to Jan 1, 1972 differ from the corresponding
TDB calendar strings by approximately 41.18 seconds.
(TDB gregorian calendar strings are produced by the
6) The error SPICE(NULLPOINTER) is signaled if either of
the input or output string pointers is null.
7) If the input string has length zero, the error SPICE(EMPTYSTRING)
will be signaled.
8) The caller must pass a value indicating the length of the output
string. If this value is not at least 2, the error
SPICE(STRINGTOOSHORT) is signaled.
9) The user's processing environment must be properly initialized by
loading a leapseconds kernel via the routine furnsh_c before
calling this routine. If a leapsecond kernel has not been
loaded, an error will be signaled by a routine in the call tree
of this routine.
A leapseconds kernel must be loaded via furnsh_c prior to
calling this routine. The kernel need be loaded only
once during a program run.
This routine handles the task of converting a double precision
representation of an epoch to a character string suitable for human
consumption. The more general routine timout_c may also be used to
convert ET to time strings.
The numerical results shown for these examples may differ across
platforms. The results depend on the SPICE kernels used as
input, the compiler and supporting libraries, and the machine
specific arithmetic implementation.
Let the value of ET be -527644192.5403653 ephemeris seconds
past J2000. Assuming that the nominal values in the kernel pool
have not been altered, the following calls
et2utc_c ( et, "C", 0, lenout, utcstr );
et2utc_c ( et, "C", 3, lenout, utcstr );
et2utc_c ( et, "D", 5, lenout, utcstr );
et2utc_c ( et, "J", 7, lenout, utcstr );
produce the following output strings
1983 APR 13 12:09:14
1983 APR 13 12:09:14.274
1983-103 // 12:09:14.27400
respectively, where lenout is the length of utcstr.
An example program.
SpiceDouble et = -527644192.5403653;
SpiceChar * leap = "naif0007.tls";
ConstSpiceChar * format;
SpiceChar * utcstr;
SpiceInt lenout = 35;
format = "J";
prec = 6;
Load the leapseconds kernel.
furnsh_c ( leap );
et2utc_c ( et , format, prec, lenout, utcstr );
printf ( "ET: %18.7f\n"
"Converted output: %s\n",
return ( 0 );
The program output is
Converted output: JD 2445438.006415
Jesperson and Fitz-Randolph, From Sundials to Atomic Clocks,
Dover Publications, New York, 1977.
C.H. Acton (JPL)
N.J. Bachman (JPL)
B.V. Semenov (JPL)
W.L. Taber (JPL)
W.M. Owen (JPL)
I.M. Underwood (JPL)
E.D. Wright (JPL)
-CSPICE Version 1.1.5, 06-APR-2009 (NJB)
Header was updated to state that fractional
seconds or days are rounded in the output
-CSPICE Version 1.1.4, 28-JAN-2008 (BVS)
Fixed typo in the ISOC example string in Detailed_Output.
-CSPICE Version 1.1.3, 16-JAN-2008 (EDW)
Corrected typos in header titles:
Detailed Input to Detailed_Input
Detailed Output to Detailed_Output
-CSPICE Version 1.1.2, 11-JAN-2006 (EDW)
Added a CHKFSTR check call on the 'format' input string.
-CSPICE Version 1.1.1, 29-JUL-2003 (NJB) (CHA)
Various header changes were made to improve clarity and
more fully explain the routine's functionality.
-CSPICE Version 1.1.0, 09-FEB-1998 (NJB) (EDW)
Re-implemented routine without dynamically allocated, temporary
strings. Added Exceptions section and corrected typo in chkout_c
-CSPICE Version 1.0.0, 25-OCT-1997 (EDW)
ephemeris time to utc