NAME

AG_User — agar user account information interface

SYNOPSIS

#include <agar/core.h>

DESCRIPTION

AG_User provides a cross-platform method for accessing information about user accounts. Different backends may be implemented (see INTERNAL API below). Agar provides the following backends:

agUserOps_dummy

No-op, returns no useful information.

agUserOps_getenv

Use the USER, UID, EUID, HOME and (optional) TMPDIR environment variables. Only USER can be queried.

agUserOps_posix

On Unix, use getpwent(3) or getpwnam_r(3). Since accessing the password database incurs startup overhead, "getenv" is the default (unless AG_InitCore(3) was called with the AG_POSIX_USERS flag option).

agUserOps_win32

On Windows, use CSIDL to locate a preferred AppData directory, and return it in the home field. Also return the preferred temporary directory in the tmp field. Other fields will contain no useful data.

agUserOps_xbox

On the Xbox console, check which drives are mounted and use either T:\ or D:\ as home.

INTERFACE

AG_UserNew *
AG_UserNew(void);

AG_User *
AG_GetUserByName(const char *name);

AG_User *
AG_GetUserByUID(Uint32 uid);

AG_User *
AG_GetRealUser(void);

AG_User *
AG_GetEffectiveUser(void);

void
AG_UserFree(AG_User *);

void
AG_SetUserOps(const AG_UserOps *ops);

The AG_UserNew() function returns a newly-allocated AG_User structure. This structure is defined as:

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;

The AG_GetUserByName() and AG_GetUserByUID() functions look up a user account by name string, or numerical identifier.

The AG_GetRealUser() and AG_GetEffectiveUser() functions return account information for the user corresponding to the real or effective UID of the calling process (if available).

The AG_UserFree() routine releases the specified AG_User structure.

The AG_User backend in use by default is determined in a platform-specific way. To register or select a specific backend, AG_SetUserOps() may be used.

BACKEND INTERFACE

The argument to AG_SetUserOps() should point to the following structure:

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;

The init() method performs any necessary initialization. The destroy() method cleans up any allocated resources.

On success the getUserByName(), getUserByUID(), getRealUser() and getEffectiveUser() methods should set the fields of the AG_User argument and return 0. On error, they should return -1.

SEE ALSO

AG_File(3), AG_Intro(3)

HISTORY

The AG_User interface first appeared in Agar 1.5.0. The "getenv" module was added in Agar 1.6.0.