diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 4b52a2f..7020e2e 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -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 \ diff --git a/doc/man/dc_datetime_gmtime.3 b/doc/man/dc_datetime_gmtime.3 new file mode 100644 index 0000000..1e4bcf5 --- /dev/null +++ b/doc/man/dc_datetime_gmtime.3 @@ -0,0 +1,94 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 . diff --git a/doc/man/dc_datetime_localtime.3 b/doc/man/dc_datetime_localtime.3 new file mode 100644 index 0000000..ec6681f --- /dev/null +++ b/doc/man/dc_datetime_localtime.3 @@ -0,0 +1,94 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 . diff --git a/doc/man/dc_datetime_mktime.3 b/doc/man/dc_datetime_mktime.3 new file mode 100644 index 0000000..a3dbccb --- /dev/null +++ b/doc/man/dc_datetime_mktime.3 @@ -0,0 +1,59 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 . diff --git a/doc/man/dc_datetime_now.3 b/doc/man/dc_datetime_now.3 new file mode 100644 index 0000000..6fffa02 --- /dev/null +++ b/doc/man/dc_datetime_now.3 @@ -0,0 +1,55 @@ +.\" +.\" libdivecomputer +.\" +.\" Copyright (C) 2017 Kristaps Dzonsons +.\" +.\" 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 . diff --git a/doc/man/dc_parser_get_datetime.3 b/doc/man/dc_parser_get_datetime.3 index 4dd6456..ba1f365 100644 --- a/doc/man/dc_parser_get_datetime.3 +++ b/doc/man/dc_parser_get_datetime.3 @@ -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