source: trunk/athena/lib/al/al_acct_create.3 @ 11758

.\" $Id: al_acct_create.3,v 1.6 1998-07-16 13:00:58 danw Exp $
.\"
.\" Copyright 1997 by the Massachusetts Institute of Technology.
.\"
.\" Permission to use, copy, modify, and distribute this
.\" software and its documentation for any purpose and without
.\" fee is hereby granted, provided that the above copyright
.\" notice appear in all copies and that both that copyright
.\" notice and this permission notice appear in supporting
.\" documentation, and that the name of M.I.T. not be used in
.\" advertising or publicity pertaining to distribution of the
.\" software without specific, written prior permission.
.\" M.I.T. makes no representations about the suitability of
.\" this software for any purpose.  It is provided "as is"
.\" without express or implied warranty.
.\"
.TH AL_ACCT_CREATE 3 "18 September 1997"
.SH NAME
al_acct_create \- Set up a local account for a user
.SH SYNOPSIS
.nf
.B #include <al.h>
.PP
.B
int al_acct_create(const char *\fIusername\fP, const char *\fIcryptpw\fP,
.B      pid_t \fIsessionpid\fP, int \fIhavecred\fP, int \fItmphomedir\fP,
.B      int **\fIwarnings\fP)
.PP
.B cc file.c -lal -lhesiod
.fi
.SH DESCRIPTION
This function ensures that local account information is set up for
.IR username .
After successful completion, the user will have information in the
local passwd and group databases and will have a home directory
accessible by the current process.  Changes to local system databases
are recorded in the sessions database (see sessions(5)) so that they
may be reverted later by
.I al_acct_revert
or
.IR al_acct_cleanup .
.PP
The meanings of the arguments to
.I al_acct_create
are as follows:
.TP 15
.I username
Gives the name of the user whose local account is to be created. 
.TP 15
.I cryptpw
If an entry is added to the local passwd database, it will use the
value of
.I cryptpw
as the encrypted passwd field if
.I cryptpw
is not NULL and if
.I /etc/nocrack
is not present.
.TP 15
.I sessionpid
Gives the pid of the login session (which should generally always be
the current process pid) to be recorded in the sessions database.
.TP 15
.I havecred
Should be nonzero if the user has cached Kerberos credentials.  If
.I havecred
is zero,
.I al_acct_create
does not attempt to get authorization to access the user's home
directory.
.TP 15
.I tmphomedir
Specifies whether to create a temporary home directory if the user's
home directory cannot be attached.
.TP 15
.I warnings
Points to a variable which may be set to an allocated array (which the
caller must free) of warning codes giving a list of possible non-fatal
error codes.  The variable will otherwise be set to NULL.  The caller
may pass a NULL pointer if it does not want warning codes.
.PP
The caller may invoke
.I al_acct_create
multiple times with the same
.I username
and
.IR sessionpid ,
e.g. once before credentials are acquired and once afterwards.
Generally,
.I tmphomedir
should be set to false for all but the last invocation, or warning
values may become confused.
.SH RETURN VALUES
.I al_acct_create
may return the following values:
.TP 15
.I AL_SUCCESS
Account creation succeeded.
.TP 15
.I AL_ENOUSER
No local or Hesiod passwd entry is available for
.IR username .
.TP 15
.I AL_EPASSWD
The user could not be added to the local passwd database.
.TP 15
.I AL_ESESSION
The user's session record could not be modified.
.TP 15
.I AL_ENOMEM
Memory was exhausted.
.TP 15
.I AL_WARNINGS
Account creation succeeded but some suboptimal condition occurred.
If
.I warnings
is non-NULL, the variable it points to is set to an allocated array of
warning codes terminated by
.IR AL_SUCCESS .
The caller must free this array.
.SH WARNINGS
Possible warning codes are:
.TP 15
.I AL_WBADSESSION
The user's session record was corrupt and treated as if it did not
exist.
.TP 15
.I AL_WGROUP
The user could not be added to the group file.
.TP 15
.I AL_WXTMPDIR
The user has a temporary home directory from a currently existing
login session.
.TP 15
.I AL_WTMPDIR
The user's home directory could not be attached; a temporary home
directory was created instead.
.TP 15
.I AL_WNOHOMEDIR
The user's home directory could not be attached and a temporary home
directory was not created.  The user has no home directory.
.TP 15
.I AL_WNOATTACH
The user's home directory was not attached because
.I /etc/noattach
is present.
.PP
If the user has a local passwd entry with a home directory which is
different from the user's Hesiod passwd entry, no home directory
attach is attempted and no homedir-related warning codes can occur.
Thus, the login application may assume that homedir-related warning
codes refer to an Athena home directory, but the application must be
handle possible errors when changing to the user's home directory.
.SH SEE ALSO
al_acct_revert(3), al_login_allowed(3), al_strerror(3), sessions(5)
.SH AUTHOR
Greg Hudson, MIT Information Systems
.br
Copyright 1997 by the Massachusetts Institute of Technology.