NAME
   sec_login_purge_context - Destroys a login context and frees its
 			    storage

 SYNOPSIS

 #include <dce/sec_login.h>

 void sec_login_purge_context(
         sec_login_handle_t *login_context,
         error_status_t *status);

 PARAMETERS

 Input

 login_context
        A pointer to an opaque handle to login context data. The login
        context contains, among other data, the account principal name
        and UUID, account restrictions, records of group membership,
        and the process home directory.  (See sec_intro for more details
        about the login context.) Note that a pointer to the handle is
        submitted, so the handle may be reset to NULL upon successful
        completion.

 Output

 status
        A pointer to the completion status.  On successful completion,
        the routine returns error_status_ok.  Otherwise, it returns an
        error.

 DESCRIPTION

 The sec_login_purge_context() routine frees any storage allocated
 for the specified login context and destroys the associated network
 credentials, if any exist.

 CAUTIONS

 Applications must be cautious when purging the current context as
 this destroys network credentials for all processes that share the
 credentials.

 FILES
       SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
              The idl file from which dce/sec_login.h was derived.

 ERRORS

 sec_login_s_default_use
              Illegal use of the default login handle occurred.

 sec_login_s_context_invalid
              The login context itself is not valid.

 error_status_ok
              The call was successful.

 EXAMPLES

 The following example illustrates use of the sec_login_purge_context()
 routine as part of a straightforward login process:

      if (sec_login_setup_identity( user_name,
                                    sec_login_no_flags,
                                    &login_context,
                                    &st)) {
         ... get password from user...

         if (sec_login_validate_identity(login_context, password,
                                  &reset_passwd, &auth_src, &st)) {

            if (!sec_login_certify_identity(login_context, &st))
                exit(error_wierd_auth_svc);

            sec_login_set_context(login_context, &st);

            if (auth_src != sec_login_auth_src_network)
               printf("no network credentials");

            if (reset_passwd) {
               ... get new password from user, reset registry record ...
            };

            sec_login_get_pwent(login_context, &pw_entry, &st);

            if (pw_entry.pw_expire < todays_date) {
               sec_login_purge_context(&login_context, &st);
               exit(0)
            }

            ... any other application specific login valid actions ...
            }

         } else {
            sec_login_purge_context(&login_context, &st);

            ... application specific login failure actions ...
         }
      }

 RELATED INFORMATION

 Functions: sec_intro
            sec_login_set_context
            sec_login_setup_identity
            sec_login_validate_identity