AG_USER(3)

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 actual default unless the AG_POSIX_USERS flag is passed to AG_InitCore(3).
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 user 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;                   /* Name for this backend */
    	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;

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

On success, the query methods getUserByName(), getUserByUID(), getRealUser() and getEffectiveUser() 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.