Agar

<-- Back to AG_Intro.3

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_dummyNo-op, returns no useful information.
agUserOps_getenvUse the USER, UID, EUID, HOME and (optional) TMPDIR environment variables. Only USER can be queried.
agUserOps_posixOn 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_win32On 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_xboxOn 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.
Csoft.net ElectronTubeStore