'\" t .\" Title: pam_set_item .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] .\" Generator: DocBook XSL Stylesheets v1.79.2 .\" Date: 08/28/2024 .\" Manual: Linux-PAM Manual .\" Source: Linux-PAM .\" Language: English .\" .TH "PAM_SET_ITEM" "3" "08/28/2024" "Linux\-PAM" "Linux\-PAM Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" pam_set_item \- set and update PAM information .SH "SYNOPSIS" .sp .ft B .nf #include .fi .ft .HP \w'int\ pam_set_item('u .BI "int pam_set_item(pam_handle_t\ *" "pamh" ", int\ " "item_type" ", const\ void\ *" "item" ");" .SH "DESCRIPTION" .PP The \fBpam_set_item\fR function allows applications and PAM service modules to access and to update PAM information of \fIitem_type\fR\&. For this a copy of the object pointed to by the \fIitem\fR argument is created\&. The following \fIitem_type\fRs are supported: .PP PAM_SERVICE .RS 4 The service name (which identifies that PAM stack that the PAM functions will use to authenticate the program)\&. .RE .PP PAM_USER .RS 4 The username of the entity under whose identity service will be given\&. That is, following authentication, \fIPAM_USER\fR identifies the local entity that gets to use the service\&. Note, this value can be mapped from something (eg\&., "anonymous") to something else (eg\&. "guest119") by any module in the PAM stack\&. As such an application should consult the value of \fIPAM_USER\fR after each call to a PAM function\&. .RE .PP PAM_USER_PROMPT .RS 4 The string used when prompting for a user\*(Aqs name\&. The default value for this string is a localized version of "login: "\&. .RE .PP PAM_TTY .RS 4 The terminal name prefixed by /dev/ for device files\&. In the past, graphical X\-based applications used to store the \fI$DISPLAY\fR variable here, but with the introduction of \fIPAM_XDISPLAY\fR this usage is deprecated\&. .RE .PP PAM_RUSER .RS 4 The requesting user name: local name for a locally requesting user or a remote user name for a remote requesting user\&. .sp Generally an application or module will attempt to supply the value that is most strongly authenticated (a local account before a remote one\&. The level of trust in this value is embodied in the actual authentication stack associated with the application, so it is ultimately at the discretion of the system administrator\&. .sp \fIPAM_RUSER@PAM_RHOST\fR should always identify the requesting user\&. In some cases, \fIPAM_RUSER\fR may be NULL\&. In such situations, it is unclear who the requesting entity is\&. .RE .PP PAM_RHOST .RS 4 The requesting hostname (the hostname of the machine from which the \fIPAM_RUSER\fR entity is requesting service)\&. That is \fIPAM_RUSER@PAM_RHOST\fR does identify the requesting user\&. In some applications, \fIPAM_RHOST\fR may be NULL\&. In such situations, it is unclear where the authentication request is originating from\&. .RE .PP PAM_AUTHTOK .RS 4 The authentication token (often a password)\&. This token should be ignored by all module functions besides \fBpam_sm_authenticate\fR(3) and \fBpam_sm_chauthtok\fR(3)\&. In the former function it is used to pass the most recent authentication token from one stacked module to another\&. In the latter function the token is used for another purpose\&. It contains the currently active authentication token\&. .RE .PP PAM_OLDAUTHTOK .RS 4 The old authentication token\&. This token should be ignored by all module functions except \fBpam_sm_chauthtok\fR(3)\&. .RE .PP PAM_CONV .RS 4 The pam_conv structure\&. See \fBpam_conv\fR(3)\&. .RE .PP The following additional items are specific to Linux\-PAM and should not be used in portable applications: .PP PAM_FAIL_DELAY .RS 4 A function pointer to redirect centrally managed failure delays\&. See \fBpam_fail_delay\fR(3)\&. .RE .PP PAM_XDISPLAY .RS 4 The name of the X display\&. For graphical, X\-based applications the value for this item should be the \fI$DISPLAY\fR variable\&. This value may be used independently of \fIPAM_TTY\fR for passing the name of the display\&. .RE .PP PAM_XAUTHDATA .RS 4 A pointer to a structure containing the X authentication data required to make a connection to the display specified by \fIPAM_XDISPLAY\fR, if such information is necessary\&. See \fBpam_xauth_data\fR(3)\&. .RE .PP PAM_AUTHTOK_TYPE .RS 4 The default action is for the module to use the following prompts when requesting passwords: "New UNIX password: " and "Retype UNIX password: "\&. The example word \fIUNIX\fR can be replaced with this item, by default it is empty\&. This item is used by \fBpam_get_authtok\fR(3)\&. .RE .PP For all \fIitem_type\fRs, other than PAM_CONV and PAM_FAIL_DELAY, \fIitem\fR is a pointer to a terminated character string\&. In the case of PAM_CONV, \fIitem\fR points to an initialized \fIpam_conv\fR structure\&. In the case of PAM_FAIL_DELAY, \fIitem\fR is a function pointer: \fBvoid (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr)\fR .PP Both, PAM_AUTHTOK and PAM_OLDAUTHTOK, will be reset before returning to the application\&. Which means an application is not able to access the authentication tokens\&. .SH "RETURN VALUES" .PP PAM_BAD_ITEM .RS 4 The application attempted to set an undefined or inaccessible item\&. .RE .PP PAM_BUF_ERR .RS 4 Memory buffer error\&. .RE .PP PAM_SUCCESS .RS 4 Data was successful updated\&. .RE .PP PAM_SYSTEM_ERR .RS 4 The \fIpam_handle_t\fR passed as first argument was invalid\&. .RE .SH "SEE ALSO" .PP \fBpam_get_item\fR(3), \fBpam_strerror\fR(3)