logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

getpwnam.3p (6718B)


  1. '\" et
  2. .TH GETPWNAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. getpwnam,
  12. getpwnam_r
  13. \(em search user database for a name
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <pwd.h>
  18. .P
  19. struct passwd *getpwnam(const char *\fIname\fP);
  20. int getpwnam_r(const char *\fIname\fP, struct passwd *\fIpwd\fP, char *\fIbuffer\fP,
  21. size_t \fIbufsize\fP, struct passwd **\fIresult\fP);
  22. .fi
  23. .SH DESCRIPTION
  24. The
  25. \fIgetpwnam\fR()
  26. function shall search the user database for an entry with a matching
  27. .IR name .
  28. .P
  29. The
  30. \fIgetpwnam\fR()
  31. function need not be thread-safe.
  32. .P
  33. Applications wishing to check for error situations should set
  34. .IR errno
  35. to 0 before calling
  36. \fIgetpwnam\fR().
  37. If
  38. \fIgetpwnam\fR()
  39. returns a null pointer and
  40. .IR errno
  41. is non-zero, an error occurred.
  42. .P
  43. The
  44. \fIgetpwnam_r\fR()
  45. function shall update the
  46. .BR passwd
  47. structure pointed to by
  48. .IR pwd
  49. and store a pointer to that structure at the location pointed to by
  50. .IR result .
  51. The structure shall contain an entry from the user database with a
  52. matching
  53. .IR name .
  54. Storage referenced by the structure is allocated from the memory
  55. provided with the
  56. .IR buffer
  57. parameter, which is
  58. .IR bufsize
  59. bytes in size. A call to
  60. .IR sysconf (_SC_GETPW_R_SIZE_MAX)
  61. returns either \-1 without changing
  62. .IR errno
  63. or an initial value suggested for the size of this buffer.
  64. A null pointer shall be returned at the location pointed to by
  65. .IR result
  66. on error or if the requested entry is not found.
  67. .SH "RETURN VALUE"
  68. The
  69. \fIgetpwnam\fR()
  70. function shall return a pointer to a
  71. .BR "struct passwd"
  72. with the structure as defined in
  73. .IR <pwd.h>
  74. with a matching entry if found. A null pointer shall be returned if the
  75. requested entry is not found, or an error occurs. If the requested
  76. entry was not found,
  77. .IR errno
  78. shall not be changed. On error,
  79. .IR errno
  80. shall be set to indicate the error.
  81. .P
  82. The application shall not modify the structure to which the return
  83. value points, nor any storage areas pointed to by pointers within the
  84. structure. The returned pointer, and pointers within the structure,
  85. might be invalidated or the structure or the storage areas might be
  86. overwritten by a subsequent call to
  87. \fIgetpwent\fR(),
  88. \fIgetpwnam\fR(),
  89. or
  90. \fIgetpwuid\fR().
  91. The returned pointer, and pointers within the structure, might
  92. also be invalidated if the calling thread is terminated.
  93. .P
  94. The
  95. \fIgetpwnam_r\fR()
  96. function shall return zero on success or if the requested entry
  97. was not found and no error has occurred. If an error has
  98. occurred, an error number shall be returned to indicate the error.
  99. .SH ERRORS
  100. These functions may fail if:
  101. .TP
  102. .BR EIO
  103. An I/O error has occurred.
  104. .TP
  105. .BR EINTR
  106. A signal was caught during
  107. \fIgetpwnam\fR().
  108. .TP
  109. .BR EMFILE
  110. All file descriptors available to the process are currently open.
  111. .TP
  112. .BR ENFILE
  113. The maximum allowable number of files is currently open in the system.
  114. .P
  115. The
  116. \fIgetpwnam_r\fR()
  117. function may fail if:
  118. .TP
  119. .BR ERANGE
  120. Insufficient storage was supplied via
  121. .IR buffer
  122. and
  123. .IR bufsize
  124. to contain the data to be referenced by the resulting
  125. .BR passwd
  126. structure.
  127. .LP
  128. .IR "The following sections are informative."
  129. .SH EXAMPLES
  130. Note that
  131. .IR sysconf (_SC_GETPW_R_SIZE_MAX)
  132. may return \-1 if there is no hard limit on the size of the buffer
  133. needed to store all the groups returned. This example shows how an
  134. application can allocate a buffer of sufficient size to work with
  135. \fIgetpwnam_r\fR().
  136. .sp
  137. .RS 4
  138. .nf
  139. long int initlen = sysconf(_SC_GETPW_R_SIZE_MAX);
  140. size_t len;
  141. if (initlen =\|= -1)
  142. /* Default initial length. */
  143. len = 1024;
  144. else
  145. len = (size_t) initlen;
  146. struct passwd result;
  147. struct passwd *resultp;
  148. char *buffer = malloc(len);
  149. if (buffer =\|= NULL)
  150. ...handle error...
  151. int e;
  152. while ((e = getpwnam_r("someuser", &result, buffer, len, &resultp))
  153. =\|= ERANGE)
  154. {
  155. size_t newlen = 2 * len;
  156. if (newlen < len)
  157. ...handle error...
  158. len = newlen;
  159. char *newbuffer = realloc(buffer, len);
  160. if (newbuffer =\|= NULL)
  161. ...handle error...
  162. buffer = newbuffer;
  163. }
  164. if (e != 0)
  165. ...handle error...
  166. free (buffer);
  167. .fi
  168. .P
  169. .RE
  170. .SS "Getting an Entry for the Login Name"
  171. .P
  172. The following example uses the
  173. \fIgetlogin\fR()
  174. function to return the name of the user who logged in; this information
  175. is passed to the
  176. \fIgetpwnam\fR()
  177. function to get the user database entry for that user.
  178. .sp
  179. .RS 4
  180. .nf
  181. #include <sys/types.h>
  182. #include <pwd.h>
  183. #include <unistd.h>
  184. #include <stdio.h>
  185. #include <stdlib.h>
  186. \&...
  187. char *lgn;
  188. struct passwd *pw;
  189. \&...
  190. if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) {
  191. fprintf(stderr, "Get of user information failed.\en"); exit(1);
  192. }
  193. \&...
  194. .fi
  195. .P
  196. .RE
  197. .SH "APPLICATION USAGE"
  198. Three names associated with the current process can be determined:
  199. .IR getpwuid (\c
  200. \fIgeteuid\fR())
  201. returns the name associated with the effective user ID of the process;
  202. \fIgetlogin\fR()
  203. returns the name associated with the current login activity; and
  204. .IR getpwuid (\c
  205. \fIgetuid\fR())
  206. returns the name associated with the real user ID of the process.
  207. .P
  208. The
  209. \fIgetpwnam_r\fR()
  210. function is thread-safe and returns values in a user-supplied buffer
  211. instead of possibly using a static data area that may be overwritten by
  212. each call.
  213. .P
  214. Portable applications should take into account that it is usual
  215. for an implementation to return \-1 from
  216. \fIsysconf\fR()
  217. indicating that there is no maximum for _SC_GETPW_R_SIZE_MAX.
  218. .SH RATIONALE
  219. None.
  220. .SH "FUTURE DIRECTIONS"
  221. None.
  222. .SH "SEE ALSO"
  223. .IR "\fIgetpwuid\fR\^(\|)",
  224. .IR "\fIsysconf\fR\^(\|)"
  225. .P
  226. The Base Definitions volume of POSIX.1\(hy2017,
  227. .IR "\fB<pwd.h>\fP",
  228. .IR "\fB<sys_types.h>\fP"
  229. .\"
  230. .SH COPYRIGHT
  231. Portions of this text are reprinted and reproduced in electronic form
  232. from IEEE Std 1003.1-2017, Standard for Information Technology
  233. -- Portable Operating System Interface (POSIX), The Open Group Base
  234. Specifications Issue 7, 2018 Edition,
  235. Copyright (C) 2018 by the Institute of
  236. Electrical and Electronics Engineers, Inc and The Open Group.
  237. In the event of any discrepancy between this version and the original IEEE and
  238. The Open Group Standard, the original IEEE and The Open Group Standard
  239. is the referee document. The original Standard can be obtained online at
  240. http://www.opengroup.org/unix/online.html .
  241. .PP
  242. Any typographical or formatting errors that appear
  243. in this page are most likely
  244. to have been introduced during the conversion of the source files to
  245. man page format. To report such errors, see
  246. https://www.kernel.org/doc/man-pages/reporting_bugs.html .