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:
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.
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
HISTORY
The
AG_User interface first appeared in
Agar 1.5.0.
The "getenv" module was added in
Agar 1.6.0.
