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

endpwent.3p (5571B)


  1. '\" et
  2. .TH ENDPWENT "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. endpwent,
  12. getpwent,
  13. setpwent
  14. \(em user database functions
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <pwd.h>
  19. .P
  20. void endpwent(void);
  21. struct passwd *getpwent(void);
  22. void setpwent(void);
  23. .fi
  24. .SH DESCRIPTION
  25. These functions shall retrieve information about users.
  26. .P
  27. The
  28. \fIgetpwent\fR()
  29. function shall return a pointer to a structure containing the broken-out
  30. fields of an entry in the user database. Each entry in the user
  31. database contains a
  32. .BR passwd
  33. structure. If the user database is not already open,
  34. \fIgetpwent\fR()
  35. shall open it and return a pointer to a
  36. .BR passwd
  37. structure containing the first entry in the database. Thereafter,
  38. it shall return a pointer to a
  39. .BR passwd
  40. structure containing the next entry in the user database. Successive
  41. calls can be used to search the entire user database.
  42. .P
  43. If an end-of-file or an error is encountered on reading,
  44. \fIgetpwent\fR()
  45. shall return a null pointer.
  46. .P
  47. An implementation that provides extended security controls may impose
  48. further implementation-defined restrictions on accessing the user
  49. database. In particular, the system may deny the existence of some or
  50. all of the user database entries associated with users other than the
  51. caller.
  52. .P
  53. The
  54. \fIsetpwent\fR()
  55. function shall rewind the user database so that the next
  56. \fIgetpwent\fR()
  57. call returns the first entry, allowing repeated searches.
  58. .P
  59. The
  60. \fIendpwent\fR()
  61. function shall close the user database.
  62. .P
  63. The
  64. \fIsetpwent\fR()
  65. and
  66. \fIendpwent\fR()
  67. functions shall not change the setting of
  68. .IR errno
  69. if successful.
  70. .P
  71. On error, the
  72. \fIsetpwent\fR()
  73. and
  74. \fIendpwent\fR()
  75. functions shall set
  76. .IR errno
  77. to indicate the error.
  78. .P
  79. Since no value is returned by the
  80. \fIsetpwent\fR()
  81. and
  82. \fIendpwent\fR()
  83. functions, an application wishing to check for error situations
  84. should set
  85. .IR errno
  86. to 0, then call the function, then check
  87. .IR errno .
  88. .P
  89. These functions need not be thread-safe.
  90. .SH "RETURN VALUE"
  91. On successful completion,
  92. \fIgetpwent\fR()
  93. shall return a pointer to a
  94. .BR passwd
  95. structure. On end-of-file,
  96. \fIgetpwent\fR()
  97. shall return a null pointer and shall not change the setting of
  98. .IR errno .
  99. On error,
  100. \fIgetpwent\fR()
  101. shall return a null pointer and
  102. .IR errno
  103. shall be set to indicate the error.
  104. .P
  105. The application shall not modify the structure to which the return
  106. value points, nor any storage areas pointed to by pointers within the
  107. structure. The returned pointer, and pointers within the structure,
  108. might be invalidated or the structure or the storage areas might be
  109. overwritten by a subsequent call to
  110. \fIgetpwuid\fR(),
  111. \fIgetpwnam\fR(),
  112. or
  113. \fIgetpwent\fR().
  114. The returned pointer, and pointers within the structure, might also
  115. be invalidated if the calling thread is terminated.
  116. .SH ERRORS
  117. These functions may fail if:
  118. .TP
  119. .BR EINTR
  120. A signal was caught during the operation.
  121. .TP
  122. .BR EIO
  123. An I/O error has occurred.
  124. .P
  125. In addition,
  126. \fIgetpwent\fR()
  127. and
  128. \fIsetpwent\fR()
  129. may fail if:
  130. .TP
  131. .BR EMFILE
  132. All file descriptors available to the process are currently open.
  133. .TP
  134. .BR ENFILE
  135. The maximum allowable number of files is currently open in the system.
  136. .LP
  137. .IR "The following sections are informative."
  138. .SH EXAMPLES
  139. .SS "Searching the User Database"
  140. .P
  141. The following example uses the
  142. \fIgetpwent\fR()
  143. function to get successive entries in the user database, returning a
  144. pointer to a
  145. .BR passwd
  146. structure that contains information about each user. The call to
  147. \fIendpwent\fR()
  148. closes the user database and cleans up.
  149. .sp
  150. .RS 4
  151. .nf
  152. #include <pwd.h>
  153. #include <stdio.h>
  154. .P
  155. void printname(uid_t uid)
  156. {
  157. struct passwd *pwd;
  158. .P
  159. setpwent();
  160. while((pwd = getpwent()) != NULL) {
  161. if (pwd->pw_uid == uid) {
  162. printf("name=%s\en",pwd->pw_name);
  163. break;
  164. }
  165. }
  166. endpwent();
  167. }
  168. .fi
  169. .P
  170. .RE
  171. .SH "APPLICATION USAGE"
  172. These functions are provided due to their historical usage.
  173. Applications should avoid dependencies on fields in the password
  174. database, whether the database is a single file, or where in the
  175. file system name space the database resides. Applications should use
  176. \fIgetpwuid\fR()
  177. whenever possible because it avoids these dependencies.
  178. .SH RATIONALE
  179. None.
  180. .SH "FUTURE DIRECTIONS"
  181. None.
  182. .SH "SEE ALSO"
  183. .IR "\fIendgrent\fR\^(\|)",
  184. .IR "\fIgetlogin\fR\^(\|)",
  185. .IR "\fIgetpwnam\fR\^(\|)",
  186. .IR "\fIgetpwuid\fR\^(\|)"
  187. .P
  188. The Base Definitions volume of POSIX.1\(hy2017,
  189. .IR "\fB<pwd.h>\fP"
  190. .\"
  191. .SH COPYRIGHT
  192. Portions of this text are reprinted and reproduced in electronic form
  193. from IEEE Std 1003.1-2017, Standard for Information Technology
  194. -- Portable Operating System Interface (POSIX), The Open Group Base
  195. Specifications Issue 7, 2018 Edition,
  196. Copyright (C) 2018 by the Institute of
  197. Electrical and Electronics Engineers, Inc and The Open Group.
  198. In the event of any discrepancy between this version and the original IEEE and
  199. The Open Group Standard, the original IEEE and The Open Group Standard
  200. is the referee document. The original Standard can be obtained online at
  201. http://www.opengroup.org/unix/online.html .
  202. .PP
  203. Any typographical or formatting errors that appear
  204. in this page are most likely
  205. to have been introduced during the conversion of the source files to
  206. man page format. To report such errors, see
  207. https://www.kernel.org/doc/man-pages/reporting_bugs.html .