ctime(3c) 맨 페이지 - 윈디하나의 솔라나라

개요

섹션
맨 페이지 이름
검색(S)

ctime(3c)

Standard C Library Functions                                         ctime(3C)



NAME
       ctime, ctime_r, localtime, localtime_r, gmtime, gmtime_r, asctime, asc‐
       time_r, tzset - convert date and time to string
       ctime_s, localtime_s, gmtime_s, asctime_s - convert date  and  time  to
       string with additional safety checks

SYNOPSIS
       #include <time.h>

       char *ctime(const time_t *clock);


       struct tm *localtime(const time_t *clock);


       struct tm *gmtime(const time_t *clock);


       char *asctime(const struct tm *tm);


       extern time_t timezone, altzone;
       extern int daylight;
       extern char *tzname[2];

       void tzset(void);


       char *ctime_r(const time_t *clock, char *buf, int buflen);


       struct tm *localtime_r(const time_t *restrict clock,
            struct tm *restrict res);


       struct tm *gmtime_r(const time_t *restrict clock,
            struct tm *restrict res);


       char *asctime_r(const struct tm *restrict tm, char *restrict buf,
            int buflen);

   Standard conforming
       cc [ flag... ] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]

       char *ctime_r(const time_t *clock, char *buf);


       char *asctime_r(const struct tm *tm, char *buf);


       #define __STDC_WANT_LIB_EXT1__ 1
       #include <time.h>


       errno_t ctime_s(char *s, rsize_t maxsize, const time_t *clock);


       errno_t asctime_s(char *s, rsize_t maxsize, const struct tm *tm);


       struct tm *gmtime_s(const time_t *restrict clock,
           struct tm *restrict result);


       struct tm *localtime_s(const time_t *restrict clock,
           struct tm *restrict result);

DESCRIPTION
       The  ctime() function converts the time pointed to by clock, represent‐
       ing the time in seconds since  the  Epoch  (00:00:00  UTC,  January  1,
       1970),  to  local  time  in the form of a 26-character string, as shown
       below. Time zone and  daylight  savings  corrections  are  made  before
       string generation. The fields are in constant width:


       Fri Sep 13 00:00:00 1986\n\0


       The ctime() function is equivalent to:


       asctime(localtime(clock))


       The ctime(), asctime(), gmtime(), and localtime() functions return val‐
       ues in one of two thread-specific  data  objects:  a  broken-down  time
       structure  and  an array of char. Execution of any of the functions can
       overwrite the information returned in either of these objects by any of
       the other functions executed by the same thread.


       The  ctime_r()  function  has  the same functionality as ctime() except
       that the caller must supply a buffer buf with length  buflen  to  store
       the  result;  buf  must  be  at least 26 bytes. The standard-conforming
       ctime_r() function does not take a buflen parameter.


       The localtime() and gmtime() functions return pointers to tm structures
       (see  below).  The localtime() function corrects for the main time zone
       and possible alternate ("daylight savings")  time  zone;  the  gmtime()
       function  converts  directly to Coordinated Universal Time (UTC), which
       is what the UNIX system uses internally.


       The localtime_r() and gmtime_r() functions have the same  functionality
       as  localtime()  and gmtime() respectively, except that the caller must
       supply a buffer res to store the result.


       The asctime() function  converts  a  tm  structure  to  a  26-character
       string,  as shown in the previous example, and returns a pointer to the
       string.


       The asctime_r() function has the same functionality as asctime() except
       that  the  caller  must  supply a buffer buf with length buflen for the
       result to be stored. The buf argument must be at least  26  bytes.  The
       standard-conforming asctime_r() function does not take a buflen parame‐
       ter. The asctime_r() function returns a pointer to buf upon success. In
       case of failure, NULL is returned and errno is set.


       Declarations  of all the functions and externals, and the tm structure,
       are in the <time.h> header. The members of the tm structure are:

         int   tm_sec;    /* seconds after the minute — [0, 60] */
                          /* for leap seconds */
         int   tm_min;    /* minutes after the hour — [0, 59] */
         int   tm_hour;   /* hour since midnight — [0, 23] */
         int   tm_mday;   /* day of the month — [1, 31] */
         int   tm_mon;    /* months since January — [0, 11] */
         int   tm_year;   /* years since 1900 */
         int   tm_wday;   /* days since Sunday — [0, 6] */
         int   tm_yday;   /* days since January 1 — [0, 365] */
         int   tm_isdst;  /* flag for alternate daylight savings time */



       The value of tm_isdst is  positive  if  daylight  savings  time  is  in
       effect, zero if daylight savings time is not in effect, and negative if
       the information is not available. Previously, the value of tm_isdst was
       defined as non-zero if daylight savings was in effect.


       The  external  time_t variable altzone contains the difference, in sec‐
       onds, between Coordinated Universal Time and the alternate  time  zone.
       The  external  variable  timezone  contains the difference, in seconds,
       between UTC and local standard time.  The  external  variable  daylight
       indicates  whether  time should reflect daylight savings time. The day‐
       light variable is set to 0 if Daylight  Savings  Time  conversions  are
       never applied for the time zone in use. Otherwise, the variable is non-
       zero.


       The daylight variable has a non-zero  value  if  Daylight  Saving  Time
       rules  apply.  A non-zero value does not necessarily mean that Daylight
       Saving Time is now in effect. It means that  Daylight  Saving  Time  is
       sometimes in effect.


       Both  timezone  and  altzone  default to 0 (UTC). The external variable
       daylight is non-zero if an alternate time zone exists.  The  time  zone
       names  are  contained in the external variable tzname, which by default
       is set to:


       char *tzname[2] = { "GMT", ""};


       These functions know about the peculiarities  of  this  conversion  for
       various  time periods for the U.S. (specifically, the years 1974, 1975,
       and 1987). They start handling the new daylight savings  time  starting
       with the first Sunday in April, 1987.


       The  tzset()  function uses the contents of the environment variable TZ
       to override the value of the different external variables. It is called
       by asctime() and can also be called by the user. If TZ is not specified
       or has an invalid setting, tzset() uses  GMT0.  See  environ(7)  for  a
       description of the TZ environment variable.


       Starting  and ending times are relative to the current local time zone.
       If the alternate time zone start and end dates and  the  time  are  not
       provided, the days for the United States that year will be used and the
       time will be 2 AM. If the start and end dates are provided but the time
       is  not  provided, the time will be 2 AM. The effects of tzset() change
       the values of the external variables timezone, altzone,  daylight,  and
       tzname.


       Note  that  in  most  installations,  TZ is set to the correct value by
       default when the user logs on, using the local  /etc/default/init  file
       (see timezone(5)).


       The asctime_s(), ctime_s(), gmtime_s(), and localtime_s() functions are
       part of the C11 bounds checking interfaces specified in the  C11  stan‐
       dard,  Annex  K.  Each  provide similar functionality to the asctime(),
       ctime(), gmtime(), and localtime() functions respectively,  except  for
       additional  checks  on  the parameters passed and explicit runtime-con‐
       straints as defined in the C11  standard.  See  runtime_constraint_han‐
       dler(3C) and INCITS/ISO/IEC 9899:2011.

RETURN VALUES
       Upon  successful  completion,  the  gmtime()  and localtime() functions
       return a pointer to a struct tm. If an error is detected, gmtime()  and
       localtime() return a null pointer.


       Upon  successful completion, the gmtime_r() and localtime_r() functions
       return the address of the structure pointed to by the res argument.  If
       an  error  is  detected,  gmtime_r()  and  localtime_r()  return a null
       pointer and set errno to indicate the error.


       Upon successful completion, the  asctime_s()  and  ctime_s()  functions
       return zero, otherwise, a non-zero value is returned.


       Upon  successful completion, the gmtime_s() and localtime_s() functions
       return result, otherwise, if the specified time cannot be converted, or
       a runtime-constraint violation is detected, the functions return a null
       pointer.

ERRORS
       The ctime_r() and asctime_r() functions will fail if:

       ERANGE    The length of the buffer supplied by the caller is not  large
                 enough to store the result.



       The gmtime(), gmtime_r(), localtime(), and localtime_r() functions will
       fail if:


       EOVERFLOW    The result cannot be represented.




       The ctime_s() and asctime_s() functions will fail if:


       EINVAL       Null pointer is passed.


       ERANGE       size argument is not a valid value.


       EOVERFLOW    The result cannot be represented.




       The gmtime_s() and localtime_s() functions will fail if:


       EINVAL    Null pointer is passed.



USAGE
       These functions do not support localized date  and  time  formats.  The
       strftime(3C) function can be used when localization is required.


       The  localtime(),  localtime_r(),  gmtime(),  gmtime_r(),  ctime(), and
       ctime_r() functions assume Gregorian dates. Times before  the  adoption
       of the Gregorian calendar will not match historical records.


       The  strftime()  function  allows more flexible formatting and supports
       locale-specific behavior. If you do not require the exact form  of  the
       result  string produced by the asctime_s() and ctime_s() function, con‐
       sider using the strftime() function instead.

EXAMPLES
       Example 1 Examples of the tzset() function.



       The tzset() function scans the contents of the environment variable and
       assigns  the  different fields to the respective variable. For example,
       the most complete setting for New Jersey in 1986 could be:


         EST5EDT4,116/2:00:00,298/2:00:00




       or simply


         EST5EDT




       An example of a southern hemisphere setting such as  the  Cook  Islands
       could be


         KDT9:30KST10:00,63/5:00,302/20:00




       In  the  longer  version  of the New Jersey example of TZ, tzname[0] is
       EST, timezone is set to 5*60*60, tzname[1] is EDT, altzone  is  set  to
       4*60*60,  the starting date of the alternate time zone is the 117th day
       at 2 AM, the ending date of the alternate time zone is the 299th day at
       2  AM  (using  zero-based  Julian  days), and daylight is set positive.
       Starting and ending times are relative to the current local time  zone.
       If  the  alternate  time  zone start and end dates and the time are not
       provided, the days for the United States that year will be used and the
       time will be 2 AM. If the start and end dates are provided but the time
       is not provided, the time will be 2 AM. The effects of tzset() are thus
       to  change the values of the external variables timezone, altzone, day‐
       light, and tzname. The ctime(), localtime(), mktime(),  and  strftime()
       functions  also  update  these external variables as if they had called
       tzset() at the time specified by the time_t or  struct  tm  value  that
       they are converting.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       tab()  box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
       TRIBUTE VALUE _ CSIEnabled _ Interface StabilityCommitted _ MT-LevelSee
       below _ StandardSee standards(7).



       The asctime(), ctime(), gmtime(), and localtime() functions are safe to
       use in multithread applications  because  they  employ  thread-specific
       data.  However,  their  use  is  discouraged  because  standards do not
       require them to be thread-safe. The asctime_r()  and  gmtime_r()  func‐
       tions  are MT-Safe. The ctime_r(), localtime_r(), and tzset() functions
       are MT-Safe in multithread applications, as  long  as  no  user-defined
       function  directly  modifies  one of the following variables: timezone,
       altzone, daylight, and tzname. These four variables are not MT-Safe  to
       access. They are modified by the tzset() function in an MT-Safe manner.
       The mktime(), localtime_r(), and ctime_r() functions call tzset().


       The asctime_s(), gmtime_s(), and localtime_s() functions cannot be used
       safely  in  a  multithreaded  application due to the runtime constraint
       handler. For more information, see  the  runtime_constraint_handler(3C)
       man page.

SEE ALSO
       time(2), Intro(3), getenv(3C), mktime(3C), printf(3C), putenv(3C), set‐
       locale(3C), strftime(3C), timezone(5), attributes(7), environ(7), stan‐
       dards(7), runtime_constraint_handler(3C)

NOTES
       When compiling multithreaded programs, see Intro(3).


       The  return  values  for  asctime(), ctime(), gmtime(), and localtime()
       point to thread-specific data whose content is overwritten by each call
       by the same thread.


       Setting the time during the interval of change from timezone to altzone
       or vice versa can produce unpredictable results. The system administra‐
       tor must change the Julian start and end days annually.


       If  tzset()  has  previously  evaluated the time zone identified by the
       value of the TZ environment variable, tzset() can  reuse  the  previous
       settings  of  the  external  variables altzone, daylight, timezone, and
       tzname[] associated with that time zone.


       Solaris 2.4 and earlier releases provided definitions of the ctime_r(),
       localtime_r(),  gmtime_r(),  and  asctime_r() functions as specified in
       POSIX.1c Draft 6. The final POSIX.1c standard changed the interface for
       ctime_r()  and  asctime_r().  Support for the Draft 6 interface is pro‐
       vided for compatibility only and  might  not  be  supported  in  future
       releases.  New  applications and libraries should use the standard-con‐
       forming interface.


       For POSIX.1c-conforming applications, the _POSIX_PTHREAD_SEMANTICS flag
       is  automatically turned on by defining the _POSIX_C_SOURCE flag with a
       value >= 199506L.


       In Solaris 10, gmtime(),  gmtime_r(),  localtime(),  and  localtime_r()
       were  updated  to  return  a null pointer if an error is detected. This
       change was based on the SUSv3 specification. See standards(7).



Oracle Solaris 11.4               11 May 2021                        ctime(3C)
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 5 CSS3