Merge from vendor branch OPENSSH:
[dragonfly.git] / contrib / libpam / doc / man / pam_setcred.3
1 .\" Hey Emacs! This file is -*- nroff -*- source.
2 .\" $Id: pam_setcred.3,v 1.1.1.1 1998/07/09 22:10:18 jdp Exp $
3 .\" $FreeBSD: src/contrib/libpam/doc/man/pam_setcred.3,v 1.2.6.2 2001/06/11 15:28:11 markm Exp $
4 .\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam_setcred.3,v 1.2 2003/06/17 04:24:02 dillon Exp $
5 .\" Copyright (c) Andrew G. Morgan 1996,1997 <morgan@parc.power.net>
6 .TH PAM_SETCRED 3 "1997 July 6" "PAM 0.58" "App. Programmers' Manual"
7 .SH NAME
8
9 pam_setcred \- set the credentials for the user
10
11 .SH SYNOPSIS
12 .B #include <security/pam_appl.h>
13 .sp
14 .BI "int pam_setcred(pam_handle_t " *pamh ", int  " flags ");"
15 .sp 2
16 .SH DESCRIPTION
17 .B pam_setcred
18
19 This function is used to establish, maintain and delete the
20 credentials of a user. It should be called after a user has been
21 authenticated and before a session is opened for the user (with
22 .BR pam_open_session "(3))."
23
24 It should be noted that credentials come in many forms. Examples
25 include: group memberships; ticket-files; and PAM environment
26 variables.  For this reason, it is important that the basic identity
27 of the user is established, by the application, prior to a call to
28 this function.  For example, the default
29 .BR PAM
30 environment variables should be set and also
31 .BR initgroups "(2) "
32 (or equivalent) should have been performed.
33
34 .SH "VALID FLAGS"
35 .TP
36 .BR PAM_ESTABLISH_CRED
37 initialize the credentials for the user.
38
39 .TP
40 .BR PAM_DELETE_CRED
41 delete the user's credentials.
42
43 .TP
44 .BR PAM_REINITIALIZE_CRED
45 delete and then initialize the user's credentials.
46
47 .TP
48 .BR PAM_REFRESH_CRED
49 extend the lifetime of the existing credentials.
50
51 .SH "RETURN VALUE"
52
53 On success
54 .BR PAM_SUCCESS
55 is returned, all other return values should be treated as errors.
56
57 .SH ERRORS
58 May be translated to text with
59 .BR pam_strerror "(3). "
60
61 .SH "CONFORMING TO"
62 DCE-RFC 86.0, October 1995.
63
64 .SH BUGS
65 .sp 2
66 none known.
67
68 .SH "SEE ALSO"
69
70 .BR pam_authenticate "(3), "
71 .BR pam_strerror "(3)"
72 and
73 .BR pam_open_session "(3). "
74
75 Also, see the three
76 .BR Linux-PAM
77 Guides, for
78 .BR "System administrators" ", "
79 .BR "module developers" ", "
80 and
81 .BR "application developers" ". "