getlogin_r Subroutine
Purpose
Gets a user's login name.
Library
Thread-Safe C Library (libc_r.a)
Syntax
Description
The getlogin_r subroutine gets a user's login name from the /etc/utmp file and places it in the Name parameter. Only the number of bytes specified by the Length parameter (including the ending null value) are placed in the Name parameter.
Applications that call the getlogin_r subroutine must allocate memory for the login name before calling the subroutine. The name buffer must be the length of the Name parameter plus an ending null value.
If the getlogin_r subroutine cannot find the login name in the utmp file or the process is not attached to a terminal, it places the LOGNAME environment variable in the name buffer. If the LOGNAME environment variable does not exist, the Name parameter is set to null and the getlogin_r subroutine returns a -1.
In UNIX03 mode, if the login name cannot be found in the /etc/utmp file or if there is no controlling terminal for the process, the getlogin_r subroutine does not place the LOGNAME environment variable in the name buffer, it just returns the error code ENXIO. This behavior is enabled by setting the environment variable XPG_SUS_ENV=ON (which enables all UNIX03 functionality) or by setting the variable XPG_GETLOGIN=ON (which just enables UNIX03 mode for the getlogin and getlogin_r subroutines).
Parameters
| Item | Description |
|---|---|
| Name | Specifies a buffer for the login name. This buffer should be the length of the Length parameter plus an ending null value. |
| Length | Specifies the total length in bytes of the Name parameter. No more bytes than the number specified by the Length parameter are placed in the Name parameter, including the ending null value. |
Return Values
If successful,
the getlogin_r function returns 0.
Otherwise, an error number is returned to indicate the error.
Error Codes
If the getlogin_r subroutine does not succeed, it returns one of the following error codes:
| Item | Description |
|---|---|
| EINVAL | Indicates that the Name parameter is not valid. |
| EMFILE | Indicates that the OPEN_MAX file descriptors are currently open in the calling process. |
| ENFILE | Indicates that the maximum allowable number of files are currently open in the system. |
| ENXIO | Indicates that the calling process has no controlling terminal. |
| ERANGE | Indicates that the value of Length is smaller than the length of the string to be returned, including the terminating null character. |
File
| Item | Description |
|---|---|
| /etc/utmp | Contains a record of users logged into the system. |