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

getgrgid.3p (6424B)


  1. '\" et
  2. .TH GETGRGID "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. getgrgid,
  12. getgrgid_r
  13. \(em get group database entry for a group ID
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <grp.h>
  18. .P
  19. struct group *getgrgid(gid_t \fIgid\fP);
  20. int getgrgid_r(gid_t \fIgid\fP, struct group *\fIgrp\fP, char *\fIbuffer\fP,
  21. size_t \fIbufsize\fP, struct group **\fIresult\fP);
  22. .fi
  23. .SH DESCRIPTION
  24. The
  25. \fIgetgrgid\fR()
  26. function shall search the group database for an entry with a matching
  27. .IR gid .
  28. .P
  29. The
  30. \fIgetgrgid\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. \fIgetgrgid\fR().
  37. If
  38. \fIgetgrgid\fR()
  39. returns a null pointer and
  40. .IR errno
  41. is set to non-zero, an error occurred.
  42. .P
  43. The
  44. \fIgetgrgid_r\fR()
  45. function shall update the
  46. .BR group
  47. structure pointed to by
  48. .IR grp
  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 group database with a
  52. matching
  53. .IR gid .
  54. Storage referenced by the group 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_GETGR_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. Upon successful completion,
  69. \fIgetgrgid\fR()
  70. shall return a pointer to a
  71. .BR "struct group"
  72. with the structure defined in
  73. .IR <grp.h>
  74. with a matching entry if one is found. The
  75. \fIgetgrgid\fR()
  76. function shall return a null pointer if either the requested entry was
  77. not found, or an error occurred. If the requested entry was not found,
  78. .IR errno
  79. shall not be changed. On error,
  80. .IR errno
  81. shall be set to indicate the error.
  82. .P
  83. The application shall not modify the structure to which the return
  84. value points, nor any storage areas pointed to by pointers within the
  85. structure. The returned pointer, and pointers within the structure,
  86. might be invalidated or the structure or the storage areas might be
  87. overwritten by a subsequent call to
  88. \fIgetgrent\fR(),
  89. \fIgetgrgid\fR(),
  90. or
  91. \fIgetgrnam\fR().
  92. The returned pointer, and pointers within the structure, might
  93. also be invalidated if the calling thread is terminated.
  94. .P
  95. If successful, the
  96. \fIgetgrgid_r\fR()
  97. function shall return zero; otherwise, an error number shall be
  98. returned to indicate the error.
  99. .SH ERRORS
  100. The
  101. \fIgetgrgid\fR()
  102. and
  103. \fIgetgrgid_r\fR()
  104. functions may fail if:
  105. .TP
  106. .BR EIO
  107. An I/O error has occurred.
  108. .TP
  109. .BR EINTR
  110. A signal was caught during
  111. \fIgetgrgid\fR().
  112. .TP
  113. .BR EMFILE
  114. All file descriptors available to the process are currently open.
  115. .TP
  116. .BR ENFILE
  117. The maximum allowable number of files is currently open in the system.
  118. .P
  119. The
  120. \fIgetgrgid_r\fR()
  121. function may fail if:
  122. .TP
  123. .BR ERANGE
  124. Insufficient storage was supplied via
  125. .IR buffer
  126. and
  127. .IR bufsize
  128. to contain the data to be referenced by the resulting
  129. .BR group
  130. structure.
  131. .LP
  132. .IR "The following sections are informative."
  133. .SH EXAMPLES
  134. Note that
  135. .IR sysconf (_SC_GETGR_R_SIZE_MAX)
  136. may return \-1 if there is no hard limit on the size of the buffer
  137. needed to store all the groups returned. This example shows how an
  138. application can allocate a buffer of sufficient size to work with
  139. \fIgetgrid_r\fR().
  140. .sp
  141. .RS 4
  142. .nf
  143. long int initlen = sysconf(_SC_GETGR_R_SIZE_MAX);
  144. size_t len;
  145. if (initlen =\|= -1)
  146. /* Default initial length. */
  147. len = 1024;
  148. else
  149. len = (size_t) initlen;
  150. struct group result;
  151. struct group *resultp;
  152. char *buffer = malloc(len);
  153. if (buffer =\|= NULL)
  154. ...handle error...
  155. int e;
  156. while ((e = getgrgid_r(42, &result, buffer, len, &resultp)) =\|= ERANGE)
  157. {
  158. size_t newlen = 2 * len;
  159. if (newlen < len)
  160. ...handle error...
  161. len = newlen;
  162. char *newbuffer = realloc(buffer, len);
  163. if (newbuffer =\|= NULL)
  164. ...handle error...
  165. buffer = newbuffer;
  166. }
  167. if (e != 0)
  168. ...handle error...
  169. free (buffer);
  170. .fi
  171. .P
  172. .RE
  173. .SS "Finding an Entry in the Group Database"
  174. .P
  175. The following example uses
  176. \fIgetgrgid\fR()
  177. to search the group database for a group ID that was previously stored
  178. in a
  179. .BR stat
  180. structure, then prints out the group name if it is found. If the group
  181. is not found, the program prints the numeric value of the group for the
  182. entry.
  183. .sp
  184. .RS 4
  185. .nf
  186. #include <sys/types.h>
  187. #include <grp.h>
  188. #include <stdio.h>
  189. \&...
  190. struct stat statbuf;
  191. struct group *grp;
  192. \&...
  193. if ((grp = getgrgid(statbuf.st_gid)) != NULL)
  194. printf(" %-8.8s", grp->gr_name);
  195. else
  196. printf(" %-8d", statbuf.st_gid);
  197. \&...
  198. .fi
  199. .P
  200. .RE
  201. .SH "APPLICATION USAGE"
  202. The
  203. \fIgetgrgid_r\fR()
  204. function is thread-safe and shall return values in a user-supplied
  205. buffer instead of possibly using a static data area that may be
  206. overwritten by each call.
  207. .P
  208. Portable applications should take into account that it is usual
  209. for an implementation to return \-1 from
  210. \fIsysconf\fR()
  211. indicating that there is no maximum for _SC_GETGR_R_SIZE_MAX.
  212. .SH RATIONALE
  213. None.
  214. .SH "FUTURE DIRECTIONS"
  215. None.
  216. .SH "SEE ALSO"
  217. .IR "\fIendgrent\fR\^(\|)",
  218. .IR "\fIgetgrnam\fR\^(\|)",
  219. .IR "\fIsysconf\fR\^(\|)"
  220. .P
  221. The Base Definitions volume of POSIX.1\(hy2017,
  222. .IR "\fB<grp.h>\fP",
  223. .IR "\fB<sys_types.h>\fP"
  224. .\"
  225. .SH COPYRIGHT
  226. Portions of this text are reprinted and reproduced in electronic form
  227. from IEEE Std 1003.1-2017, Standard for Information Technology
  228. -- Portable Operating System Interface (POSIX), The Open Group Base
  229. Specifications Issue 7, 2018 Edition,
  230. Copyright (C) 2018 by the Institute of
  231. Electrical and Electronics Engineers, Inc and The Open Group.
  232. In the event of any discrepancy between this version and the original IEEE and
  233. The Open Group Standard, the original IEEE and The Open Group Standard
  234. is the referee document. The original Standard can be obtained online at
  235. http://www.opengroup.org/unix/online.html .
  236. .PP
  237. Any typographical or formatting errors that appear
  238. in this page are most likely
  239. to have been introduced during the conversion of the source files to
  240. man page format. To report such errors, see
  241. https://www.kernel.org/doc/man-pages/reporting_bugs.html .