FlapJackApps/libdc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document the date/time functions

Browse Source
This commit is contained in:
Kristaps Dzonsons 2017-01-12 13:14:48 +01:00 committed by Jef Driesen
parent 77b0cebb35
commit 6c356604ec
6 changed files with 315 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/man/Makefile.am
View File

@ -9,6 +9,10 @@ dist_man_MANS = \
dc_context_new.3 \
dc_context_set_logfunc.3 \
dc_context_set_loglevel.3 \
dc_datetime_gmtime.3 \
dc_datetime_localtime.3 \
dc_datetime_mktime.3 \
dc_datetime_now.3 \
dc_descriptor_free.3 \
dc_descriptor_get_product.3 \
dc_descriptor_get_vendor.3 \

94
doc/man/dc_datetime_gmtime.3 Normal file
View File

@ -0,0 +1,94 @@
.\"
.\" libdivecomputer
.\"
.\" Copyright (C) 2017 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" This library is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Lesser General Public
.\" License as published by the Free Software Foundation; either
.\" version 2.1 of the License, or (at your option) any later version.
.\"
.\" This library is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
.\" Lesser General Public License for more details.
.\"
.\" You should have received a copy of the GNU Lesser General Public
.\" License along with this library; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
.\" MA 02110-1301 USA
.\"
.Dd January 11, 2017
.Dt DC_DATETIME_GMTIME 3
.Os
.Sh NAME
.Nm dc_datetime_gmtime
.Nd convert an timestamp to GMT date and time
.Sh LIBRARY
.Lb libdivecomputer
.Sh SYNOPSIS
.In libdivecomputer/datetime.h
.Ft dc_datetime_t *
.Fo dc_datetime_gmtime
.Fa "dc_datetime_t *result"
.Fa "dc_ticks_t ticks"
.Fc
.Sh DESCRIPTION
Convert an integral timestamp
.Fa ticks
created with
.Xr dc_datetime_now 3
or
.Xr dc_datetime_mktime 3
into a broken-down GMT representation in
.Fa result .
The filled-in value consists of the
.Va year ,
.Va month ,
.Va day ,
.Va hour ,
.Va minute ,
and
.Va second
fields.
.Pp
.Em Note :
unlike in
.Vt "struct tm" ,
the value for
.Va year
is normalised, not less 1900; moreover, the value for
.Va month
is from one, not zero.
.Pp
The
.Nm
function may internally invoke libc's
.Xr gmtime 3 ,
or if available,
.Xr gmtime_r 3 .
.Sh RETURN VALUES
This returns the
.Fa result
pointer on success.
It returns
.Dv NULL
if
.Fa ticks
cannot be sanely converted or if
.Fa result
is
.Dv NULL .
.Sh SEE ALSO
.Xr dc_datetime_localtime 3 ,
.Xr dc_datetime_mktime 3 ,
.Xr dc_datetime_new 3
.Sh AUTHORS
The
.Lb libdivecomputer
library was written by
.An Jef Driesen ,
.Mt jef@libdivecomputer.org .
The manpages were written by
.An Kristaps Dzonsons ,
.Mt kristaps@bsd.lv .

94
doc/man/dc_datetime_localtime.3 Normal file
View File

@ -0,0 +1,94 @@
.\"
.\" libdivecomputer
.\"
.\" Copyright (C) 2017 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" This library is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Lesser General Public
.\" License as published by the Free Software Foundation; either
.\" version 2.1 of the License, or (at your option) any later version.
.\"
.\" This library is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
.\" Lesser General Public License for more details.
.\"
.\" You should have received a copy of the GNU Lesser General Public
.\" License along with this library; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
.\" MA 02110-1301 USA
.\"
.Dd January 11, 2017
.Dt DC_DATETIME_LOCALTIME 3
.Os
.Sh NAME
.Nm dc_datetime_localtime
.Nd convert an timestamp to local date and time
.Sh LIBRARY
.Lb libdivecomputer
.Sh SYNOPSIS
.In libdivecomputer/datetime.h
.Ft dc_datetime_t *
.Fo dc_datetime_localtime
.Fa "dc_datetime_t *result"
.Fa "dc_ticks_t ticks"
.Fc
.Sh DESCRIPTION
Convert an integral timestamp
.Fa ticks
created with
.Xr dc_datetime_now 3
or
.Xr dc_datetime_mktime 3
into a broken-down local-time representation in
.Fa result .
The filled-in value consists of the
.Va year ,
.Va month ,
.Va day ,
.Va hour ,
.Va minute ,
and
.Va second
fields.
.Pp
.Em Note :
unlike in
.Vt "struct tm" ,
the value for
.Va year
is normalised, not less 1900; moreover, the value for
.Va month
is from one, not zero.
.Pp
The
.Nm
function may internally invoke libc's
.Xr localtime 3 ,
or if available,
.Xr localtime_r 3 .
.Sh RETURN VALUES
This returns the
.Fa result
pointer on success.
It returns
.Dv NULL
if
.Fa ticks
cannot be sanely converted or if
.Fa result
is
.Dv NULL .
.Sh SEE ALSO
.Xr dc_datetime_gmtime 3 ,
.Xr dc_datetime_mktime 3 ,
.Xr dc_datetime_new 3
.Sh AUTHORS
The
.Lb libdivecomputer
library was written by
.An Jef Driesen ,
.Mt jef@libdivecomputer.org .
The manpages were written by
.An Kristaps Dzonsons ,
.Mt kristaps@bsd.lv .

59
doc/man/dc_datetime_mktime.3 Normal file
View File

@ -0,0 +1,59 @@
.\"
.\" libdivecomputer
.\"
.\" Copyright (C) 2017 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" This library is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Lesser General Public
.\" License as published by the Free Software Foundation; either
.\" version 2.1 of the License, or (at your option) any later version.
.\"
.\" This library is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
.\" Lesser General Public License for more details.
.\"
.\" You should have received a copy of the GNU Lesser General Public
.\" License along with this library; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
.\" MA 02110-1301 USA
.\"
.Dd January 11, 2017
.Dt DC_DATETIME_MKTIME 3
.Os
.Sh NAME
.Nm dc_datetime_mktime
.Nd convert an local date and time to a timestamp
.Sh LIBRARY
.Lb libdivecomputer
.Sh SYNOPSIS
.In libdivecomputer/datetime.h
.Ft dc_ticks_t
.Fo dc_datetime_mktime
.Fa "const dc_datetime_t *dt"
.Fc
.Sh DESCRIPTION
Convert a broken-down local date and time created with
.Xr dc_datetime_localtime 3
into an integral timestamp.
.Pp
The
.Nm
function may internally invoke libc's
.Xr mktime 3 .
.Sh RETURN VALUES
This returns the integral time-stamp or -1 if the given date and time
may not sanely be converted.
.Sh SEE ALSO
.Xr dc_datetime_gmtime 3 ,
.Xr dc_datetime_localtime 3 ,
.Xr dc_datetime_new 3
.Sh AUTHORS
The
.Lb libdivecomputer
library was written by
.An Jef Driesen ,
.Mt jef@libdivecomputer.org .
The manpages were written by
.An Kristaps Dzonsons ,
.Mt kristaps@bsd.lv .

55
doc/man/dc_datetime_now.3 Normal file
View File

@ -0,0 +1,55 @@
.\"
.\" libdivecomputer
.\"
.\" Copyright (C) 2017 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" This library is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Lesser General Public
.\" License as published by the Free Software Foundation; either
.\" version 2.1 of the License, or (at your option) any later version.
.\"
.\" This library is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
.\" Lesser General Public License for more details.
.\"
.\" You should have received a copy of the GNU Lesser General Public
.\" License along with this library; if not, write to the Free Software
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
.\" MA 02110-1301 USA
.\"
.Dd January 11, 2017
.Dt DC_DATETIME_NOW 3
.Os
.Sh NAME
.Nm dc_datetime_now
.Nd return the current integral timestamp
.Sh LIBRARY
.Lb libdivecomputer
.Sh SYNOPSIS
.In libdivecomputer/datetime.h
.Ft dc_ticks_t
.Fo dc_datetime_now
.Fc
.Sh DESCRIPTION
Get the current system timestamp as an integral value.
.Pp
The
.Nm
function may invoke libc's
.Xr time 3 .
.Sh RETURN VALUES
This always returns the system time.
.Sh SEE ALSO
.Xr dc_datetime_gmtime 3 ,
.Xr dc_datetime_localtime 3 ,
.Xr dc_datetime_mktime 3
.Sh AUTHORS
The
.Lb libdivecomputer
library was written by
.An Jef Driesen ,
.Mt jef@libdivecomputer.org .
The manpages were written by
.An Kristaps Dzonsons ,
.Mt kristaps@bsd.lv .

9
doc/man/dc_parser_get_datetime.3
View File

@ -40,6 +40,13 @@ previously initialised with
.Xr dc_parser_set_data 3 .
This returns the broken-down time-stamp of the dive in the local time of
the dive.
.Pp
The
.Nm
function may internally invoke
.Xr dc_datetime_gmtime 3
or
.Xr dc_datetime_localtime 3 .
.Sh RETURN VALUES
Returns
.Dv DC_STATUS_SUCCESS
@ -48,6 +55,8 @@ if the date and time were retrieved,
if the date and time are not supported by the device, or other error
messages on further failure.
.Sh SEE ALSO
.Xr dc_datetime_gmtime 3 ,
.Xr dc_datetime_localtime 3 ,
.Xr dc_parser_set_data 3
.Sh AUTHORS
The