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

getgrnam.3p (5917B)


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