getpwnam_r()--Get User Information for User Name

Syntax

 #include <sys/types.h>
 #include <pwd.h>

 int getpwnam_r(const char *name, struct passwd  
 *pwd, char *buffer, size_t bufsize,   
 struct passwd **result);

  Service Program Name: QSYPAPI

  Default Public Authority: *USE

  Threadsafe: Yes

The getpwnam_r() function updates the passwd structure pointed to by pwd and stores a pointer to that structure in the location pointed to by result. The structure contains an entry from the user database with a matching name.

Parameters

name: (Input) A pointer to a user profile name.
pwd: (Input) A pointer to a passwd structure.
buffer: (Input) A pointer to a buffer from which memory is allocated to hold storage areas referenced by the structure pwd.
bufsize: (Input) The size of buffer in bytes.
result: (Input) A pointer to a location in which a pointer to the updated passwd structure is stored. If an error occurs or if the requested entry cannot be found, a NULL pointer is stored in this location.

The struct passwd, which is defined in the pwd.h header file, 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 will be set to NULL.

See QlgGetpwnam_r()--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. Go to _r version

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

0: getpwnam_r was successful.
Any other value: Failure: The return value contains an error number indicating the error.

Error Conditions

If getpwnam_r() is not successful, the return value usually indicates one of the following errors. Under some conditions, the value 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.
[ERANGE]	Insufficient storage was supplied through buffer and bufsize to contain the data to be referenced by the resulting group structure.
[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 Functions)
getpwnam()--Get User Information for User Name

Example

See Code disclaimer information for information pertaining to code examples.

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.

#include <sys/types.h>
#include <pwd.h>
#include <stdio.h>
#include <errno.h>

main()
{
  struct passwd pd;
  struct passwd* pwdptr=&pd;
  struct passwd* tempPwdPtr;
  char pwdbuffer[200];
  int  pwdlinelen = sizeof(pwdbuffer);

  if ((getpwnam_r("MYUSER",pwdptr,pwdbuffer,pwdlinelen,&tempPwdPtr))!=0)
     perror("getpwnam_r() error.");
  else
  {
     printf("\nThe 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: V4R4

Top | UNIX-Type APIs | APIs by category