.\" Copyright (c) 2013-2022 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT 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 SUCH DAMAGE.
.\"
.Dd December 21, 2022
.Dt AG_USER 3
.Os Agar 1.7
.Sh NAME
.Nm AG_User
.Nd agar user account information interface
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
.Ed
.Sh DESCRIPTION
.Nm
provides a cross-platform method for accessing information about user accounts.
Different backends may be implemented (see
.Sx INTERNAL API
below).
Agar provides the following backends:
.Pp
.Bl -tag -compact -width "agUserOps_posix "
.It agUserOps_dummy
No-op, returns no useful information.
.It agUserOps_getenv
Use the
.Va USER ,
.Va UID ,
.Va EUID ,
.Va HOME
and (optional)
.Va TMPDIR
environment variables.
Only
.Va USER
can be queried.
.It agUserOps_posix
On Unix, use
.Xr getpwent 3
or
.Xr getpwnam_r 3 .
Since accessing the password database incurs startup overhead, "getenv"
is the default (unless
.Xr AG_InitCore 3
was called with the
.Dv AG_POSIX_USERS
flag option).
.It agUserOps_win32
On Windows, use CSIDL to locate a preferred
.Pa AppData
directory, and return it in the
.Va home
field.
Also return the preferred temporary directory in the
.Va tmp
field.
Other fields will contain no useful data.
.It agUserOps_xbox
On the Xbox console, check which drives are mounted and use
either T:\\ or D:\\ as home.
.El
.Sh INTERFACE
.nr nS 1
.Ft "AG_UserNew *"
.Fn AG_UserNew "void"
.Pp
.Ft "AG_User *"
.Fn AG_GetUserByName "const char *name"
.Pp
.Ft "AG_User *"
.Fn AG_GetUserByUID "Uint32 uid"
.Pp
.Ft "AG_User *"
.Fn AG_GetRealUser "void"
.Pp
.Ft "AG_User *"
.Fn AG_GetEffectiveUser "void"
.Pp
.Ft "void"
.Fn AG_UserFree "AG_User *"
.Pp
.Ft void
.Fn AG_SetUserOps "const AG_UserOps *ops"
.Pp
.nr nS 0
The
.Fn AG_UserNew
function returns a newly-allocated
.Nm
structure.
This structure is defined as:
.Bd -literal -offset indent
.\" SYNTAX(c)
typedef struct ag_user {
	char   name[AG_USER_NAME_MAX];  /* User name */
	Uint   flags;
#define AG_USER_NO_ACCOUNT 0x01 /* Not a real account */
	char  *passwd;          /* Encrypted password */
	Uint32 uid;             /* User ID */
	Uint32 gid;             /* Group ID */
	char  *loginClass;      /* Login class */
	char  *gecos;           /* Honeywell login info */
	char  *home;            /* Home directory */
	char  *shell;           /* Default shell */
	char  *tmp;             /* Temp. directory */
	AG_TAILQ_ENTRY(ag_user) users;
} AG_User;
.Ed
.Pp
The
.Fn AG_GetUserByName
and
.Fn AG_GetUserByUID
functions look up a user account by name string, or numerical identifier.
.Pp
The
.Fn AG_GetRealUser
and
.Fn AG_GetEffectiveUser
functions return account information for the user corresponding to
the real or effective UID of the calling process (if available).
.Pp
The
.Fn AG_UserFree
routine releases the specified
.Nm
structure.
.Pp
The
.Nm
backend in use by default is determined in a platform-specific
way.
To register or select a specific backend,
.Fn AG_SetUserOps
may be used.
.\" MANLINK(AG_UserOps)
.Sh BACKEND INTERFACE
The argument to
.Fn AG_SetUserOps
should point to the following structure:
.Bd -literal
.\" SYNTAX(c)
typedef struct ag_user_ops {
	const char *name;           /* Backend name */
	void (*init)(void);
	void (*destroy)(void);
	int  (*getUserByName)(AG_User *, const char *);
	int  (*getUserByUID)(AG_User *, Uint32);
	int  (*getRealUser)(AG_User *);
	int  (*getEffectiveUser)(AG_User *);
} AG_UserOps;
.Ed
.Pp
The
.Fn init
method performs any necessary initialization.
The
.Fn destroy
method cleans up any allocated resources.
.Pp
On success the
.Fn getUserByName ,
.Fn getUserByUID ,
.Fn getRealUser
and
.Fn getEffectiveUser
methods should set the fields of the
.Ft AG_User
argument and return 0.
On error, they should return -1.
.Sh SEE ALSO
.Xr AG_File 3 ,
.Xr AG_Intro 3
.Sh HISTORY
The
.Nm
interface first appeared in Agar 1.5.0.
The "getenv" module was added in Agar 1.6.0.