contrib/tzcode/newstrftime.3

   1 .\" Based on the UCB file whose copyright information appears below.
   2 .\" Copyright (c) 1989, 1991 The Regents of the University of California.
   3 .\" All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to Berkeley by
   6 .\" the American National Standards Committee X3, on Information
   7 .\" Processing Systems.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     from: @(#)strftime.3    5.12 (Berkeley) 6/29/91
  34 .\"     $Id: strftime.3,v 1.4 1993/12/15 20:33:00 jtc Exp $
  35 .\"
  36 .TH NEWSTRFTIME 3
  37 .SH NAME
  38 strftime \- format date and time
  39 .SH SYNOPSIS
  40 .nf
  41 .ie \n(.g .ds - \f(CW-\fP
  42 .el ds - \-
  43 .B #include <time.h>
  44 .PP
  45 .B "size_t strftime(char *restrict buf, size_t maxsize,"
  46 .B "    char const *restrict format, struct tm const *restrict timeptr);"
  47 .PP
  48 .B cc ... \-ltz
  49 .fi
  50 .SH DESCRIPTION
  51 .ie '\(en'' .ds en \-
  52 .el .ds en \(en
  53 .ie '\(lq'' .ds lq \&"\"
  54 .el .ds lq \(lq\"
  55 .ie '\(rq'' .ds rq \&"\"
  56 .el .ds rq \(rq\"
  57 .de q
  58 \\$3\*(lq\\$1\*(rq\\$2
  59 ..
  60 The
  61 .I strftime
  62 function formats the information from
  63 .I timeptr
  64 into the buffer
  65 .I buf
  66 according to the string pointed to by
  67 .IR format .
  68 .PP
  69 The
  70 .I format
  71 string consists of zero or more conversion specifications and
  72 ordinary characters.
  73 All ordinary characters are copied directly into the buffer.
  74 A conversion specification consists of a percent sign
  75 .Ql %
  76 and one other character.
  77 .PP
  78 No more than
  79 .I maxsize
  80 characters are placed into the array.
  81 If the total number of resulting characters, including the terminating
  82 null character, is not more than
  83 .IR maxsize ,
  84 .I strftime
  85 returns the number of characters in the array, not counting the
  86 terminating null.
  87 Otherwise, zero is returned.
  88 .PP
  89 Each conversion specification is replaced by the characters as
  90 follows which are then copied into the buffer.
  91 .TP
  92 %A
  93 is replaced by the locale's full weekday name.
  94 .TP
  95 %a
  96 is replaced by the locale's abbreviated weekday name.
  97 .TP
  98 %B
  99 is replaced by the locale's full month name.
 100 .TP
 101 %b or %h
 102 is replaced by the locale's abbreviated month name.
 103 .TP
 104 %C
 105 is replaced by the century (a year divided by 100 and truncated to an integer)
 106 as a decimal number (00\*(en99).
 107 .TP
 108 %c
 109 is replaced by the locale's appropriate date and time representation.
 110 .TP
 111 %D
 112 is replaced by the date in the format %m/%d/%y.
 113 .TP
 114 %d
 115 is replaced by the day of the month as a decimal number (01\*(en31).
 116 .TP
 117 %e
 118 is replaced by the day of month as a decimal number (1\*(en31);
 119 single digits are preceded by a blank.
 120 .TP
 121 %F
 122 is replaced by the date in the format %Y\*-%m\*-%d.
 123 .TP
 124 %G
 125 is replaced by the ISO 8601 year with century as a decimal number.
 126 .TP
 127 %g
 128 is replaced by the ISO 8601 year without century as a decimal number (00\*(en99).
 129 .TP
 130 %H
 131 is replaced by the hour (24-hour clock) as a decimal number (00\*(en23).
 132 .TP
 133 %I
 134 is replaced by the hour (12-hour clock) as a decimal number (01\*(en12).
 135 .TP
 136 %j
 137 is replaced by the day of the year as a decimal number (001\*(en366).
 138 .TP
 139 %k
 140 is replaced by the hour (24-hour clock) as a decimal number (0\*(en23);
 141 single digits are preceded by a blank.
 142 .TP
 143 %l
 144 is replaced by the hour (12-hour clock) as a decimal number (1\*(en12);
 145 single digits are preceded by a blank.
 146 .TP
 147 %M
 148 is replaced by the minute as a decimal number (00\*(en59).
 149 .TP
 150 %m
 151 is replaced by the month as a decimal number (01\*(en12).
 152 .TP
 153 %n
 154 is replaced by a newline.
 155 .TP
 156 %p
 157 is replaced by the locale's equivalent of either AM or PM.
 158 .TP
 159 %R
 160 is replaced by the time in the format %H:%M.
 161 .TP
 162 %r
 163 is replaced by the locale's representation of 12-hour clock time
 164 using AM/PM notation.
 165 .TP
 166 %S
 167 is replaced by the second as a decimal number (00\*(en60).
 168 .TP
 169 %s
 170 is replaced by the number of seconds since the Epoch (see newctime(3)).
 171 .TP
 172 %T
 173 is replaced by the time in the format %H:%M:%S.
 174 .TP
 175 %t
 176 is replaced by a tab.
 177 .TP
 178 %U
 179 is replaced by the week number of the year (Sunday as the first day of
 180 the week) as a decimal number (00\*(en53).
 181 .TP
 182 %u
 183 is replaced by the weekday (Monday as the first day of the week)
 184 as a decimal number (1\*(en7).
 185 .TP
 186 %V
 187 is replaced by the week number of the year (Monday as the first day of
 188 the week) as a decimal number (01\*(en53).  If the week containing January
 189 1 has four or more days in the new year, then it is week 1; otherwise
 190 it is week 53 of the previous year, and the next week is week 1.
 191 .TP
 192 %W
 193 is replaced by the week number of the year (Monday as the first day of
 194 the week) as a decimal number (00\*(en53).
 195 .TP
 196 %w
 197 is replaced by the weekday (Sunday as the first day of the week)
 198 as a decimal number (0\*(en6).
 199 .TP
 200 %X
 201 is replaced by the locale's appropriate time representation.
 202 .TP
 203 %x
 204 is replaced by the locale's appropriate date representation.
 205 .TP
 206 %Y
 207 is replaced by the year with century as a decimal number.
 208 .TP
 209 %y
 210 is replaced by the year without century as a decimal number (00\*(en99).
 211 .TP
 212 %Z
 213 is replaced by the time zone name,
 214 or by the empty string if this is not determinable.
 215 .TP
 216 %z
 217 is replaced by the offset from the Prime Meridian
 218 in the format +HHMM or \*-HHMM as appropriate,
 219 with positive values representing locations east of Greenwich,
 220 or by the empty string if this is not determinable.
 221 The numeric time zone \*-0000 is used when the time is Universal Time
 222 but local time is indeterminate; by convention this is used for
 223 locations while uninhabited, and corresponds to a zero offset when the
 224 time zone abbreviation begins with
 225 .q "\*-" .
 226 .TP
 227 %%
 228 is replaced by a single %.
 229 .TP
 230 %+
 231 is replaced by the date and time in date(1) format.
 232 .SH SEE ALSO
 233 date(1),
 234 getenv(3),
 235 newctime(3),
 236 newtzset(3),
 237 time(2),
 238 tzfile(5)