DragonFly On-Line Manual Pages

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
              authenticated 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
       getpwuid() or malloc().

SEE ALSO
       read(2), write(2), getpwuid(3), ph_open(3), ph_change(3)

University of Illinois             Oct 2002                        ph_login(3)