'\" t -*- coding: UTF-8 -*-
.if \n(.g .ds T< \\FC
.if \n(.g .ds T> \\F[\n[.fam]]
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.if \n(.g .mso www.tmac
.TH sg_get_user_stats 3 2019-03-08 libstatgrab ""
.SH NAME
sg_get_user_stats, sg_get_user_stats_r, sg_free_user_stats \- get the current logged in users
.SH SYNOPSIS
'nh
.nf
\*(T<#include <statgrab.h>\*(T>
.fi
.sp 1
.PP
.fi
.ad l
\*(T<sg_user_stats *\fBsg_get_user_stats\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_user_stats *\fBsg_get_user_stats_r\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_error \fBsg_free_user_stats\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(sg_user_stats *\fIdata\fR);\*(T>
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
The user statistics module delivers some information about logged on
users. Each logon is treated separately. Both statistic get functions,
\*(T<\fBsg_get_user_stats\fR\*(T>() and
\*(T<\fBsg_get_user_stats_r\fR\*(T>(), return a vector of
\*(T<sg_user_stats\*(T> with
\*(T<entries\*(T> elements.
.PP
\fBAPI Shortcut\fR
.TS
allbox ;
l | l | l.
T{
function
T}	T{
returns
T}	T{
data owner
T}
.T&
l | l | l
l | l | l.
T{
sg_get_user_stats
T}	T{
\*(T<sg_user_stats\*(T> *
T}	T{
libstatgrab (thread local)
T}
T{
sg_get_user_stats_r
T}	T{
\*(T<sg_user_stats\*(T> *
T}	T{
caller
T}
.TE
.PP
The \*(T<sg_user_stats\*(T> vector received from
\*(T<\fBsg_get_user_stats_r\fR\*(T>() must be freed using
\*(T<\fBsg_free_user_stats\fR\*(T>() when not needed any more. The
caller is responsible for doing it.
.SH "RETURN VALUES"
The structure returned is of type
\*(T<sg_user_stats\*(T>.
.PP
.nf
\*(T<
typedef struct {
        char *login_name;
        char *record_id;
        size_t record_id_size;
        char *device;
        char *hostname;
        pid_t pid;
        time_t login_time;
        time_t systime;
} sg_user_stats;
    \*(T>
.fi
.TP 
\*(T<login_name\*(T>
The username which was used to log in
.TP 
\*(T<record_id\*(T>
Record identifier of host database containing login information
(not necessarily 0-terminated)
.TP 
\*(T<record_id_size\*(T>
Size of the record identifier
.TP 
\*(T<device\*(T>
Device name (eg. "pts/0") of the tty assigned to the login
session
.TP 
\*(T<hostname\*(T>
(remote) Hostname from where the user is logged on, eg.
"infoterm7.some.kind.of.domain.local", "localhost",
"10.42.17.4" or ":0.0" (in case it's a local logon
via new xterm)
.TP 
\*(T<pid\*(T>
Process identifier of the process which made the entry to
the logged on users database
.TP 
\*(T<login_time\*(T>
Timestamp (time in seconds since epoch) when the user logged on
.TP 
\*(T<systime\*(T>
The timestamp when the above stats where collected in seconds
since epoch
.SH "SEE ALSO"
\fBstatgrab\fR(3)
.SH WEBSITE
\(lahttps://libstatgrab.org/\(ra