diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/getlogin.3p')
| -rw-r--r-- | man-pages-posix-2017/man3p/getlogin.3p | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/getlogin.3p b/man-pages-posix-2017/man3p/getlogin.3p new file mode 100644 index 0000000..5e76617 --- /dev/null +++ b/man-pages-posix-2017/man3p/getlogin.3p @@ -0,0 +1,229 @@ +'\" et +.TH GETLOGIN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getlogin, +getlogin_r +\(em get login name +.SH SYNOPSIS +.LP +.nf +#include <unistd.h> +.P +char *getlogin(void); +int getlogin_r(char *\fIname\fP, size_t \fInamesize\fP); +.fi +.SH DESCRIPTION +The +\fIgetlogin\fR() +function shall return a pointer to a string containing the user name +associated by the login activity with the controlling terminal of the +current process. If +\fIgetlogin\fR() +returns a non-null pointer, then that pointer points to the name that +the user logged in under, even if there are several login names with +the same user ID. +.P +The +\fIgetlogin\fR() +function need not be thread-safe. +.P +The +\fIgetlogin_r\fR() +function shall put the name associated by the login activity with the +controlling terminal of the current process in the character array +pointed to by +.IR name . +The array is +.IR namesize +characters long and should have space for the name and the terminating +null character. The maximum size of the login name is +{LOGIN_NAME_MAX}. +.P +If +\fIgetlogin_r\fR() +is successful, +.IR name +points to the name the user used at login, even if there are several +login names with the same user ID. +.P +The +\fIgetlogin\fR() +and +\fIgetlogin_r\fR() +functions may make use of file descriptors 0, 1, and 2 to find the +controlling terminal of the current process, examining each in turn +until the terminal is found. If in this case none of these three file +descriptors is open to the controlling terminal, these functions may +fail. The method used to find the terminal associated with a file +descriptor may depend on the file descriptor being open to the actual +terminal device, not +.BR /dev/tty . +.SH "RETURN VALUE" +Upon successful completion, +\fIgetlogin\fR() +shall return a pointer to the login name or a null pointer if the +user's login name cannot be found. Otherwise, it shall return a null +pointer and set +.IR errno +to indicate the error. +.P +The application shall not modify the string returned. The returned +pointer might be invalidated or the string content might be overwritten +by a subsequent call to +\fIgetlogin\fR(). +The returned pointer and the string content might also be invalidated +if the calling thread is terminated. +.P +If successful, the +\fIgetlogin_r\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.TP +.BR ENOTTY +None of the file descriptors 0, 1, or 2 is open to the controlling +terminal of the current process. +.TP +.BR ENXIO +The calling process has no controlling terminal. +.P +The +\fIgetlogin_r\fR() +function may fail if: +.TP +.BR ERANGE +The value of +.IR namesize +is smaller than the length of the string to be returned including the +terminating null character. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting the User Login Name" S +.P +The following example calls the +\fIgetlogin\fR() +function to obtain the name of the user associated with the calling +process, and passes this information to the +\fIgetpwnam\fR() +function to get the associated user database information. +.sp +.RS 4 +.nf + +#include <unistd.h> +#include <sys/types.h> +#include <pwd.h> +#include <stdio.h> +\&... +char *lgn; +struct passwd *pw; +\&... +if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) { + fprintf(stderr, "Get of user information failed.\en"); exit(1); + } +.fi +.P +.RE +.SH "APPLICATION USAGE" +Three names associated with the current process can be determined: +.IR getpwuid (\c +\fIgeteuid\fR()) +shall return the name associated with the effective user ID of the +process; +\fIgetlogin\fR() +shall return the name associated with the current login activity; and +.IR getpwuid (\c +\fIgetuid\fR()) +shall return the name associated with the real user ID of the process. +.P +The +\fIgetlogin_r\fR() +function is thread-safe and returns values in a user-supplied buffer +instead of possibly using a static data area that may be overwritten by +each call. +.SH RATIONALE +The +\fIgetlogin\fR() +function returns a pointer to the user's login name. The same user ID +may be shared by several login names. If it is desired to get the user +database entry that is used during login, the result of +\fIgetlogin\fR() +should be used to provide the argument to the +\fIgetpwnam\fR() +function. (This might be used to determine the user's login shell, +particularly where a single user has multiple login shells with +distinct login names, but the same user ID.) +.P +The information provided by the +.IR cuserid (\|) +function, which was originally defined in the POSIX.1\(hy1988 standard and subsequently +removed, can be obtained by the following: +.sp +.RS 4 +.nf + +getpwuid(geteuid()) +.fi +.P +.RE +.P +while the information provided by historical implementations of +.IR cuserid (\|) +can be obtained by: +.sp +.RS 4 +.nf + +getpwuid(getuid()) +.fi +.P +.RE +.P +The thread-safe version of this function places the user name in a +user-supplied buffer and returns a non-zero value if it fails. The +non-thread-safe version may return the name in a static data area that +may be overwritten by each call. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetpwnam\fR\^(\|)", +.IR "\fIgetpwuid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<limits.h>\fP", +.IR "\fB<unistd.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |