getpwnam()--Get User Information for User Name
Syntax
#include <pwd.h> struct passwd *getpwnam(const char *name);Service Program Name: QSYPAPI
Default Public Authority: *USE
Threadsafe: No
The getpwnam() function returns a pointer to an object of type struct passwd containing an entry from the user database with a matching name.
Parameters
- name
- (Input) A pointer to a user profile name.
Authorities
*READ authority is required to the user profile associated with the name. If the user does not have *READ authority, only the user name, user ID, and group ID values are returned.
Note: Adopted authority is not used.
Return Value
- struct passwd *
- getpwnam() was successful. The return value points to
static data of the format struct passwd, which is defined in the
pwd.h header file. This storage is overwritten on each call to
this function. This static storage area is also used by the
getpwuid() function. The struct passwd has the following
elements:
char * pw_name User name uid_t pw_uid User ID uid_t pw_gid Group ID of the user's first group. If the user does not have a first group, the gid value will be set to 0. char * pw_dir Initial working directory. If the user does not have *READ authority to the user profile, the pw_dir pointer will be set to NULL. char * pw_shell Initial user program. If the user does not have *READ authority to the user profile, the pw_shell pointer will be set to NULL.
- NULL pointer
- getpwnam() was not successful. The errno global variable is set to indicate the error.
See QlgGetpwnam()--Get User Information for User Name (using NLS-enabled path name) for a description and an example where the path name is returned in any CCSID.
Error Conditions
If getpwnam() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.
| Error condition | Additional information |
|---|---|
| [EAGAIN] |
The user profile associated with the name is currently locked by another process. |
| [EC2] |
Detected pointer that is not valid. |
| [EINVAL] |
Value is not valid. Check the job log for messages. |
| [ENOENT] |
The user profile associated with the name was not found. |
| [ENOMEM] |
The user profile associated with the UID has exceeded its storage limit or is unable to allocate memory. |
| [EUNKNOWN] |
Unknown system state. Check the job log for a CPF9872 message. If there is no message, verify that the home directory field in the user profile can be displayed. |
Usage Notes
The initial working directory is returned in the CCSID value of the job.
Related Information
- The <pwd.h> file (see Header
Files for UNIX®-Type APIs)
- getpwnam_r()--Get User Information for User
Name
- QlgGetpwnam()--Get User Information for User Name (using NLS-enabled path name)
Example
The following example gets the user database information for the user name of MYUSER. The UID is 22. The gid of MYUSER's first group is 1012. The initial directory is /home/MYUSER. The initial user program is *LIBL/QCMD.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <pwd.h>
main()
{
struct passwd *pd;
if (NULL == (pd = getpwnam("MYUSER")))
perror("getpwnam() error.");
else
{
printf("The user name is: %s\n", pd->pw_name);
printf("The user id is: %u\n", pd->pw_uid);
printf("The group id is: %u\n", pd->pw_gid);
printf("The initial directory is: %s\n", pd->pw_dir);
printf("The initial user program is: %s\n", pd->pw_shell);
}
}
Output:
The user name is: MYUSER The user id is: 22 The group id is: 1012 The initial directory is: /home/MYUSER The initial user program is: *LIBL/QCMD
API introduced: V3R1