library: document and tests for uptime functions

man pages for the three procps_uptime* functions and simple
test scripts for same functions.

3 files changed, 120 insertions, 0 deletions

diff --git a/doc/procps_uptime.3 b/doc/procps_uptime.3
new file mode 100644
index 0000000..912aa3c
--- /dev/null
+++ b/doc/procps_uptime.3
@@ -0,0 +1,58 @@
+.\" (C) Copyright 2016 Craig Small <csmall@enc.com.au>
+.\"
+.\" %%%LICENSE_START(LGPL_2.1+)
+.\" This manual 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 manual 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
+.\" %%%LICENSE_END
+.\"
+.TH PROCPS_UPTIME 3 2016-04-16 "libproc-2"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.SH NAME
+procps_uptime \-
+provide the uptime and idle time in seconds
+.SH SYNOPSIS
+.B #include <proc/procps.h>
+.sp
+.BI "int procps_uptime(double * " uptime_secs ", double * " idle_secs ");"
+.sp
+Link with \fI\-lprocps\fP.
+.SH DESCRIPTION
+The function
+.BR procps_uptime ()
+fills the location of the two double points with the current sytem uptime
+and idle time.
+.SH RETURN VALUE
+.BR procps_uptime ()
+returns a positive integer which is the uptime on success. On failure, it
+returns a negative integer to one of the values defined below.
+.TP
+.B -ERANGE
+Unable to parse the uptime file.
+.PP
+.BR procps_uptime ()
+may also return any (negated) value that \fBfopen\fR() may set errno to.
+
+.SH FILES
+.TP
+.I /proc/uptime
+The raw values for uptime and idle time.
+
+.SH VERSIONS
+.B procps_uptime()
+first appeared in libproc-2 version 0.0.
+
+.SH SEE ALSO
+.BR fopen (3),
+.BR proc (5).
diff --git a/doc/procps_uptime_sprint.3 b/doc/procps_uptime_sprint.3
new file mode 100644
index 0000000..6aba6ce
--- /dev/null
+++ b/doc/procps_uptime_sprint.3
@@ -0,0 +1,61 @@
+.\" (C) Copyright 2016 Craig Small <csmall@enc.com.au>
+.\"
+.\" %%%LICENSE_START(LGPL_2.1+)
+.\" This manual 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 manual 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
+.\" %%%LICENSE_END
+.\"
+.TH PROCPS_uptime_sprint_SPRINT 3 2016-04-16 "libproc-2"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.SH NAME
+procps_uptime_sprint \-
+provide the uptime and idle time in seconds
+.SH SYNOPSIS
+.B #include <proc/procps.h>
+.sp
+.B char procps_uptime_sprint(void);
+.br
+.B char procps_uptime_sprint_short(void);
+.sp
+Link with \fI\-lprocps\fP.
+.SH DESCRIPTION
+The functions
+.BR procps_uptime_sprint ()
+and
+.BR procps_uptime_sprint_short ()
+return a string from a statically allocated buffer which displays uptime
+and other system statistics. This format is similar to
+.BR w (1)
+
+.SH RETURN VALUE
+Both functions return a formatted string on success and NULL on failure.
+.PP
+.B procps_uptime_sprint
+returns a string displaying the uptime, number of users and load average.
+.PP
+.B procps_uptime_sprint_short
+returns a string displaying the uptime only.
+
+.SH VERSIONS
+.B procps_uptime_sprint()
+and
+.B procps_uptime_sprint_short()
+first appeared in libproc-2 version 0.0.
+
+.SH SEE ALSO
+.BR fopen (3),
+.BR procps_loadavg (3),
+.BR procps_uptime (3),
+.BR proc (5).
diff --git a/doc/procps_uptime_sprint_short.3 b/doc/procps_uptime_sprint_short.3
new file mode 100644
index 0000000..3c7bb14
--- /dev/null
+++ b/doc/procps_uptime_sprint_short.3
@@ -0,0 +1 @@
+.so man3/procps_uptime_sprint.1