exec_asuser(2)                                           exec_asuser(2)

  exec_asuser

  NAME

    execl_asuser(), execlp_asuser(), execle_asuser(), execv_asuser(),
    execve_asuser(), execvp_asuser() - execute a file as another user

  SYNOPSIS

    #include 
    extern char **environ;

    int execl_asuser (const struct usersec userdata, const char *path,
                     const char *arg ...)
    int execlp_asuser (const struct usersec userdata, const char *file,
                      const char *arg ...)
    int execle_asuser (const struct usersec userdata, const char *path,
                      const char *arg ... char *const envp[])
    int execv_asuser (const struct usersec userdata, const char *path,
                     char *const argv[])
    int execve_asuser (const struct usersec userdata, const char *path,
                      char *const argv[], char *const envp[])
    int execvp_asuser (const struct usersec userdata, const char *file,
                      char *const argv[])

  DESCRIPTION

    The exec_asuser(2) family of functions replaces the current process image
    with a new process image, run as the user specified in the structure
    userdata. These functions do a similar job to the calls setuid()/exec() on
    a BSD or SVR4 system. However, they do not behave identically, so do not
    rely heavily on this analogy.

    You should use these functions instead of setuid() and exec() if you can
    supply a user name and password when executing the file. This allows the
    calling program to run with lower privileges because setuid() can only be
    called by programs running under the SYSTEM account or the local or domain
    Administrator account. Also, a program executed using the exec_asuser()
    functions can access network resources if run using a domain account; this
    is not possible when setuid() is used to establish the privilege level of
    the program.

    Except for the initial userdata argument, the arguments to the
    exec_asuser(2) functions are identical to the corresponding exec(2)
    functions; see that reference page for more details.

    The first argument is a user security structure, struct usersec, which is
    defined in :

    struct usersec {
        char * user;
        char * domain;
        char * password;
        int logontype; Defaults to 0
        int logonprovider; Defaults to 0
    };

    The new process image maintains the following attributes and resources:
    Calling Process Attribute              Behavior

    Open file descriptors                  Remain open, unless close-on-exec
                                           flag FD_CLOEXEC is set

    Directory streams                      Closed

    Signals set to default action          Set to default action

    Signals set to be ignored              Set to be ignored

    Signals set to be caught               Set to default action

    Real user ID                           Determined by usersec

    Real group ID                          Determined by usersec

    Supplementary group ID                 Determined by usersec

    Effective user ID                      Determined by usersec

    Effective group ID                     Determined by usersec

    Process ID                             Inherited

    Parent process ID                      Inherited

    Process group ID                       Inherited

    Session membership                     Inherited

    Time left until alarm clock signal     Inherited

    Current working directory              Inherited

    Root directory                         Inherited

    File mode creation mask                Inherited

    Process signal mask                    Inherited

    Pending signals                        Inherited

    There can be a performance degradation if a process changes identity to a
    user who does not have permission to be located in the current working
    directory. The best solution is to chdir(2) after a call to
    exec_asuser(2), to a directory known to be permitted for the new identity.

    If these functions fail, the uids and gids for the remainder of the
    process are unspecified. The uid and gid of the process may remain the
    same as before this function was called or may be changed to that of the
    user defined in the usersec structure.

  RETURN VALUES

    On success, the exec_asuser(2) functions don't return. If they fail, they
    set errno and return -1.

  ERRORS

    The exec_asuser functions can set errno to any of the following values:

    [E2BIG]
        The argument list was too long.

    [EACCES]
        Search permission was denied for a directory in the path or the new
        process image file wasn't executable.

    [EINVAL]
        The values for logontype or logonprovider were bad.

    [ENAMETOOLONG]
        Some component of path was greater than {NAME_MAX}, or the entire
        pathname exceeded {PATH_MAX}.

    [ENOENT]
        One or more components of path doesn't exist, or the path or file
        argument is an empty string.

    [ENOEXEC]
        For execl_asuser(2), execv_asuser(2), execle_asuser(2), and
        execve_asuser(2), the new process image file has the appropriate
        access permission, but is not in the proper format.

    [ENOMEM]
        Not enough memory to load the new process image.

    [ENOTDIR]
        Some component of the path prefix of path is not a directory.

    [EPERM]
        The user-domain-password combination is invalid.

  SEE ALSO

    authenticateuser(2)

    exec(2)

    fork(2)

    setuid(2)

  USAGE NOTES

    All of these functions are thread safe.

    None of these functions are async-signal safe.