ph_login(3) C Library Calls ph_login(3)NAME
ph_login, ph_logout, ph_suser - PH server authentication routines
SYNOPSIS
#include <phclient.h>
int ph_login(PH *ph, char *alias, int authtype, void *auth);
int ph_logout(PH *ph);
int ph_suser(PH *ph, char *alias);
int ph_passwd(PH *ph, char *newpass);
char *ph_whoami(PH *ph);
VERSION
This man page documents version 1.2 of libphclient.
DESCRIPTION
The ph_login() function authenticates the user alias to the PH server
associated with the PH handle ph. The authtype argument must be set to
one of the following values:
PH_AUTH_EMAIL
Email authentication. If the connection was established using
the PH_OPEN_PRIVPORT flag to ph_open(), the user will be authen‐
ticated if the local username and hostname match the value of
the user's email field on the PH server. The auth argument is
ignored.
PH_AUTH_PASSWORD
Encrypted password authentication. The auth argument is the
user's password.
PH_AUTH_CLEAR
Cleartext password authentication. Use of this authentication
method is not recommended, since it is inherently insecure. The
auth argument is the user's password.
The ph_logout() function logs the currently logged-in user out of the
PH server. The session goes back to being an unpriveledged, anonymous
session.
The ph_suser() function allows a PH hero to assume the identity of any
arbitrary user without hero priveledges. The alias argument indicates
the user whose priveledges should be assumed.
The ph_passwd() function changes the password of the currently logged-
in user. The newpass argument is the new password.
The ph_whoami() function returns the name of the currently logged-in
user, or NULL if no user is logged in.
RETURN VALUE
On successful completion, ph_login() returns 0. If authentication is
denied by the server, it returns PH_ERR_NOTLOG. On failure, it returns
-1 and sets errno to an appropriate value.
On successful completion, ph_logout() returns 0. If no user is logged
in, it returns PH_ERR_NOTLOG. On other errors, it returns -1 and sets
errno to an appropriate value.
The ph_suser() function returns 0 on success, PH_ERR_NOTHERO if the
calling user is not a PH hero, or PH_ERR_NOTLOG if no user is logged
in. On failure, it returns -1 and sets errno to an appropriate value.
The ph_passwd() function returns 0 on success, or PH_ERR_NOTLOG if no
user is logged in. It can also fail with the same values returned by
ph_change(3). On failure, it returns -1 and sets errno.
ERRORS
The functions described here may fail with any error from the functions
read() or write().
The ph_login() function will return the following errors:
EINVAL The authtype is invalid.
EINVAL Invalid data is read from the server.
EAGAIN The server responds with a temporary failure.
In addition, ph_login() may fail with any error from the functions get‐
pwuid() or malloc().
SEE ALSOread(2), write(2), getpwuid(3), ph_open(3), ph_change(3)University of Illinois Oct 2002 ph_login(3)
