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

getpwuid.3p (7621B)


  1. '\" et
  2. .TH GETPWUID "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. getpwuid,
  12. getpwuid_r
  13. \(em search user database for a user ID
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <pwd.h>
  18. .P
  19. struct passwd *getpwuid(uid_t \fIuid\fP);
  20. int getpwuid_r(uid_t \fIuid\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. \fIgetpwuid\fR()
  26. function shall search the user database for an entry with a matching
  27. .IR uid .
  28. .P
  29. The
  30. \fIgetpwuid\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. \fIgetpwuid\fR().
  37. If
  38. \fIgetpwuid\fR()
  39. returns a null pointer and
  40. .IR errno
  41. is set to non-zero, an error occurred.
  42. .P
  43. The
  44. \fIgetpwuid_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 uid .
  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. \fIgetpwuid\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 also
  92. be invalidated if the calling thread is terminated.
  93. .P
  94. If successful, the
  95. \fIgetpwuid_r\fR()
  96. function shall return zero; otherwise, an error number shall be
  97. returned to indicate the error.
  98. .SH ERRORS
  99. These functions may fail if:
  100. .TP
  101. .BR EIO
  102. An I/O error has occurred.
  103. .TP
  104. .BR EINTR
  105. A signal was caught during
  106. \fIgetpwuid\fR().
  107. .TP
  108. .BR EMFILE
  109. All file descriptors available to the process are currently open.
  110. .TP
  111. .BR ENFILE
  112. The maximum allowable number of files is currently open in the system.
  113. .P
  114. The
  115. \fIgetpwuid_r\fR()
  116. function may fail if:
  117. .TP
  118. .BR ERANGE
  119. Insufficient storage was supplied via
  120. .IR buffer
  121. and
  122. .IR bufsize
  123. to contain the data to be referenced by the resulting
  124. .BR passwd
  125. structure.
  126. .LP
  127. .IR "The following sections are informative."
  128. .SH EXAMPLES
  129. Note that
  130. .IR sysconf (_SC_GETPW_R_SIZE_MAX)
  131. may return \-1 if there is no hard limit on the size of the buffer
  132. needed to store all the groups returned. This example shows how an
  133. application can allocate a buffer of sufficient size to work with
  134. \fIgetpwuid_r\fR().
  135. .sp
  136. .RS 4
  137. .nf
  138. long int initlen = sysconf(_SC_GETPW_R_SIZE_MAX);
  139. size_t len;
  140. if (initlen =\|= -1)
  141. /* Default initial length. */
  142. len = 1024;
  143. else
  144. len = (size_t) initlen;
  145. struct passwd result;
  146. struct passwd *resultp;
  147. char *buffer = malloc(len);
  148. if (buffer =\|= NULL)
  149. ...handle error...
  150. int e;
  151. while ((e = getpwuid_r(42, &result, buffer, len, &resultp)) =\|= ERANGE)
  152. {
  153. size_t newlen = 2 * len;
  154. if (newlen < len)
  155. ...handle error...
  156. len = newlen;
  157. char *newbuffer = realloc(buffer, len);
  158. if (newbuffer =\|= NULL)
  159. ...handle error...
  160. buffer = newbuffer;
  161. }
  162. if (e != 0)
  163. ...handle error...
  164. free (buffer);
  165. .fi
  166. .P
  167. .RE
  168. .SS "Getting an Entry for the Root User"
  169. .P
  170. The following example gets the user database entry for the user with
  171. user ID 0 (root).
  172. .sp
  173. .RS 4
  174. .nf
  175. #include <sys/types.h>
  176. #include <pwd.h>
  177. \&...
  178. uid_t id = 0;
  179. struct passwd *pwd;
  180. .P
  181. pwd = getpwuid(id);
  182. .fi
  183. .P
  184. .RE
  185. .SS "Finding the Name for the Effective User ID"
  186. .P
  187. The following example defines
  188. .IR pws
  189. as a pointer to a structure of type
  190. .BR passwd ,
  191. which is used to store the structure pointer returned by the call to
  192. the
  193. \fIgetpwuid\fR()
  194. function. The
  195. \fIgeteuid\fR()
  196. function shall return the effective user ID of the calling process;
  197. this is used as the search criteria for the
  198. \fIgetpwuid\fR()
  199. function. The call to
  200. \fIgetpwuid\fR()
  201. shall return a pointer to the structure containing that user ID value.
  202. .sp
  203. .RS 4
  204. .nf
  205. #include <unistd.h>
  206. #include <sys/types.h>
  207. #include <pwd.h>
  208. \&...
  209. struct passwd *pws;
  210. pws = getpwuid(geteuid());
  211. .fi
  212. .P
  213. .RE
  214. .SS "Finding an Entry in the User Database"
  215. .P
  216. The following example uses
  217. \fIgetpwuid\fR()
  218. to search the user database for a user ID that was previously stored in
  219. a
  220. .BR stat
  221. structure, then prints out the user name if it is found. If the user
  222. is not found, the program prints the numeric value of the user ID for
  223. the entry.
  224. .sp
  225. .RS 4
  226. .nf
  227. #include <sys/types.h>
  228. #include <pwd.h>
  229. #include <stdio.h>
  230. \&...
  231. struct stat statbuf;
  232. struct passwd *pwd;
  233. \&...
  234. if ((pwd = getpwuid(statbuf.st_uid)) != NULL)
  235. printf(" %-8.8s", pwd->pw_name);
  236. else
  237. printf(" %-8d", statbuf.st_uid);
  238. .fi
  239. .P
  240. .RE
  241. .SH "APPLICATION USAGE"
  242. Three names associated with the current process can be determined:
  243. .IR getpwuid (\c
  244. \fIgeteuid\fR())
  245. returns the name associated with the effective user ID of the process;
  246. \fIgetlogin\fR()
  247. returns the name associated with the current login activity; and
  248. .IR getpwuid (\c
  249. \fIgetuid\fR())
  250. returns the name associated with the real user ID of the process.
  251. .P
  252. The
  253. \fIgetpwuid_r\fR()
  254. function is thread-safe and returns values in a user-supplied buffer
  255. instead of possibly using a static data area that may be overwritten by
  256. each call.
  257. .P
  258. Portable applications should take into account that it is usual
  259. for an implementation to return \-1 from
  260. \fIsysconf\fR()
  261. indicating that there is no maximum for _SC_GETPW_R_SIZE_MAX.
  262. .SH RATIONALE
  263. None.
  264. .SH "FUTURE DIRECTIONS"
  265. None.
  266. .SH "SEE ALSO"
  267. .IR "\fIgetpwnam\fR\^(\|)",
  268. .IR "\fIgeteuid\fR\^(\|)",
  269. .IR "\fIgetuid\fR\^(\|)",
  270. .IR "\fIgetlogin\fR\^(\|)",
  271. .IR "\fIsysconf\fR\^(\|)"
  272. .P
  273. The Base Definitions volume of POSIX.1\(hy2017,
  274. .IR "\fB<pwd.h>\fP",
  275. .IR "\fB<sys_types.h>\fP"
  276. .\"
  277. .SH COPYRIGHT
  278. Portions of this text are reprinted and reproduced in electronic form
  279. from IEEE Std 1003.1-2017, Standard for Information Technology
  280. -- Portable Operating System Interface (POSIX), The Open Group Base
  281. Specifications Issue 7, 2018 Edition,
  282. Copyright (C) 2018 by the Institute of
  283. Electrical and Electronics Engineers, Inc and The Open Group.
  284. In the event of any discrepancy between this version and the original IEEE and
  285. The Open Group Standard, the original IEEE and The Open Group Standard
  286. is the referee document. The original Standard can be obtained online at
  287. http://www.opengroup.org/unix/online.html .
  288. .PP
  289. Any typographical or formatting errors that appear
  290. in this page are most likely
  291. to have been introduced during the conversion of the source files to
  292. man page format. To report such errors, see
  293. https://www.kernel.org/doc/man-pages/reporting_bugs.html .