Page MenuHomeFreeBSD
Differential D36515 Diff 110630 contrib/tzcode/stdtime/ctime.3

Changeset View

Standalone View

View Options

contrib/tzcode/stdtime/ctime.3

Show All 24 Lines
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE. .\" SUCH DAMAGE.
.\" .\"
.\" From: @(#)ctime.3 8.1 (Berkeley) 6/4/93 .\" From: @(#)ctime.3 8.1 (Berkeley) 6/4/93
.\" $FreeBSD$ .\" $FreeBSD$
.\" .\"
.Dd March 4, 2022 .Dd September 16, 2022
.Dt CTIME 3 .Dt CTIME 3
.Os .Os
.Sh NAME .Sh NAME
.Nm asctime , .Nm asctime ,
.Nm asctime_r , .Nm asctime_r ,
.Nm ctime , .Nm ctime ,
.Nm ctime_r , .Nm ctime_r ,
.Nm difftime , .Nm difftime ,
▲ Show 20 Lines • Show All 47 Lines • ▼ Show 20 Lines
.Fn localtime .Fn localtime
converts the time value pointed at by converts the time value pointed at by
.Fa clock , .Fa clock ,
and returns a pointer to a and returns a pointer to a
.Dq Fa struct tm .Dq Fa struct tm
(described below) which contains (described below) which contains
the broken-out time information for the value after adjusting for the current the broken-out time information for the value after adjusting for the current
time zone (and any other factors such as Daylight Saving Time). time zone (and any other factors such as Daylight Saving Time).
When the specified time translates to a year that will not fit in an
rpokalaUnsubmitted
Not Done
Inline Actions

"passed-in"

rpokala: "passed-in"
.Dv int ,
impUnsubmitted
Done
Inline Actions

Please specify what kind of integer. Is it an int, time_t or ????
This is too vague because nearly all times can fit into an integral type if it's a long long, but only a limited subset if it is a int32_t.

imp: Please specify what kind of integer. Is it an int, time_t or ???? This is too vague because…
mckusickUnsubmitted
Done
Inline Actions

The field for year in the tm structure is defined as int'. So it depends on how the architecture defines int'. Perhaps the wording should be:

When the passed in time translates to a year that will not fit in in an int' for architectures that define int' to be int32_t,

mckusick: The field for year in the tm structure is defined as `int'. So it depends on how the…
impUnsubmitted
Done
Inline Actions

When the passed in time translates to a year that overflows the hosts'
.Dv int
type.

is likely fine. And it makes perfect sense now where we go awry and what the impact will be (in practical terms, not much).

imp: When the passed in time translates to a year that overflows the hosts' .Dv int type. is likely…
.Fn localtime
returns NULL.
impUnsubmitted
Done
Inline Actions

I hate to keep picking nits, please forgive me for not realizing this comment sooner.

I think we can just remove the 'for architectures where int is 32-bits' entirely and have it read OK.

When the specified time translates to a year that will not fit in an
.Dv int ,
.Fn localtime
returns NULL.
imp: I hate to keep picking nits, please forgive me for not realizing this comment sooner. I think…
Time zone adjustments are performed as specified by the Time zone adjustments are performed as specified by the
impUnsubmitted
Done
Inline Actions

"for architectures where
.Dv int
is 32-bits,"

instead, because int32_t is defined in terms of things like int, long, etc so this may confuse people.

imp: "for architectures where .Dv int is 32-bits," instead, because int32_t is defined in terms of…
.Ev TZ .Ev TZ
environment variable (see environment variable (see
.Xr tzset 3 ) . .Xr tzset 3 ) .
The function The function
.Fn localtime .Fn localtime
uses uses
.Xr tzset 3 .Xr tzset 3
to initialize time conversion information if to initialize time conversion information if
▲ Show 20 Lines • Show All 252 Lines • ▼ Show 20 Lines
The functions The functions
.Fn asctime_r , .Fn asctime_r ,
.Fn ctime_r , .Fn ctime_r ,
.Fn gmtime_r , .Fn gmtime_r ,
and and
.Fn localtime_r .Fn localtime_r
have been available since have been available since
.Fx 8.0 . .Fx 8.0 .
.Sh BUGS .Sh BUGS
Except for Except for
.Fn difftime , .Fn difftime ,
.Fn mktime , .Fn mktime ,
and the and the
.Fn \&_r .Fn \&_r
mckusickUnsubmitted
Done
Inline Actions

If you add a new section, I propose that you use a more standard section header:

.Sh RETURN VALUES
When successful, the
.Fn localtime
function return a pointer to a
.Dq Fa struct tm .
When the passed in time translates to a year that will not fit in an integer type,
.Fn localtime
returns NULL.

mckusick: If you add a new section, I propose that you use a more standard section header: .Sh RETURN…
impUnsubmitted
Done
Inline Actions

Is it a 'integral type' or is it specifically time_t?

I'd be tempted to add some vague statement about 'the standard allows any error to cause a NULL return. FreeBSD will return an error when...'

imp: Is it a 'integral type' or is it specifically time_t? I'd be tempted to add some vague…
variants of the other functions, variants of the other functions,
these functions leave their result in an internal static object and return these functions leave their result in an internal static object and return
a pointer to that object. a pointer to that object.
Subsequent calls to these Subsequent calls to these
function will modify the same object. function will modify the same object.
.Pp .Pp
The C Standard provides no mechanism for a program to modify its current The C Standard provides no mechanism for a program to modify its current
local timezone setting, and the local timezone setting, and the
.Tn POSIX Ns No \&-standard .Tn POSIX Ns No \&-standard
impUnsubmitted
Not Done
Inline Actions

Should these reference the specific POSIX standard?
I know that's likely for another commit since this is just cleaning up .Tn, but seeing the change makes me wonder as we've often moved that way in other man pages.

imp: Should these reference the specific POSIX standard? I know that's likely for another commit…
method is not reentrant. method is not reentrant.
(However, thread-safe implementations are provided (However, thread-safe implementations are provided
in the in the
.Tn POSIX .Tn POSIX
threaded environment.) threaded environment.)
.Pp .Pp
The The
.Va tm_zone .Va tm_zone
Show All 14 Lines