1.\" Generated from pam_get_item.c by gendoc.pl
2.\" $OpenPAM: pam_get_item.c 938 2017-04-30 21:34:42Z des $
3.Dd February 24, 2019
4.Dt PAM_GET_ITEM 3
5.Os
6.Sh NAME
7.Nm pam_get_item
8.Nd get PAM information
9.Sh SYNOPSIS
10.In sys/types.h
11.In security/pam_appl.h
12.Ft "int"
13.Fn pam_get_item "const pam_handle_t *pamh" "int item_type" "const void **item"
14.Sh DESCRIPTION
15The
16.Fn pam_get_item
17function stores a pointer to the item specified by
18the
19.Fa item_type
20argument in the location pointed to by the
21.Fa item
22argument.
23The item is retrieved from the PAM context specified by the
24.Fa pamh
25argument.
26If
27.Fn pam_get_item
28fails, the
29.Fa item
30argument is untouched.
31.Pp
32The following item types are recognized:
33.Bl -tag -width 18n
34.It Dv PAM_SERVICE
35The name of the requesting service.
36.It Dv PAM_USER
37The name of the user the application is trying to
38authenticate.
39.It Dv PAM_TTY
40The name of the current terminal.
41.It Dv PAM_RHOST
42The name of the applicant's host.
43.It Dv PAM_CONV
44A
45.Vt struct pam_conv
46describing the current conversation
47function.
48.It Dv PAM_AUTHTOK
49The current authentication token.
50.It Dv PAM_OLDAUTHTOK
51The expired authentication token.
52.It Dv PAM_RUSER
53The name of the applicant.
54.It Dv PAM_USER_PROMPT
55The prompt to use when asking the applicant for a user
56name to authenticate as.
57.It Dv PAM_AUTHTOK_PROMPT
58The prompt to use when asking the applicant for an
59authentication token.
60.It Dv PAM_OLDAUTHTOK_PROMPT
61The prompt to use when asking the applicant for an
62expired authentication token prior to changing it.
63.It Dv PAM_HOST
64The name of the host the application runs on.
65.El
66.Pp
67See
68.Xr pam_start 3
69for a description of
70.Vt struct pam_conv .
71.Pp
72.Sh RETURN VALUES
73The
74.Fn pam_get_item
75function returns one of the following values:
76.Bl -tag -width 18n
77.It Bq Er PAM_SUCCESS
78Success.
79.It Bq Er PAM_BAD_ITEM
80Unrecognized or restricted item.
81.El
82.Sh SEE ALSO
83.Xr pam 3 ,
84.Xr pam_set_item 3 ,
85.Xr pam_start 3 ,
86.Xr pam_strerror 3
87.Sh STANDARDS
88.Rs
89.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
90.%D "June 1997"
91.Re
92.Sh AUTHORS
93The
94.Fn pam_get_item
95function and this manual page were
96developed for the
97.Fx
98Project by ThinkSec AS and Network Associates Laboratories, the
99Security Research Division of Network Associates, Inc.\& under
100DARPA/SPAWAR contract N66001-01-C-8035
101.Pq Dq CBOSS ,
102as part of the DARPA CHATS research program.
103.Pp
104The OpenPAM library is maintained by
105.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .
106