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

getgroups.3p (4329B)

    

  1. '\" et
  2. .TH GETGROUPS "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. getgroups
  12. \(em get supplementary group IDs
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. int getgroups(int \fIgidsetsize\fP, gid_t \fIgrouplist\fP[]);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIgetgroups\fR()
  23. function shall fill in the array
  24. .IR grouplist
  25. with the current supplementary group IDs of the calling process. It is
  26. implementation-defined whether
  27. \fIgetgroups\fR()
  28. also returns the effective group ID in the
  29. .IR grouplist
  30. array.
  31. .P
  32. The
  33. .IR gidsetsize
  34. argument specifies the number of elements in the array
  35. .IR grouplist .
  36. The actual number of group IDs stored in the array shall be returned.
  37. The values of array entries with indices greater than or equal to the
  38. value returned are undefined.
  39. .P
  40. If
  41. .IR gidsetsize
  42. is 0,
  43. \fIgetgroups\fR()
  44. shall return the number of group IDs that it would otherwise return
  45. without modifying the array pointed to by
  46. .IR grouplist .
  47. .P
  48. If the effective group ID of the process is returned with the
  49. supplementary group IDs, the value returned shall always be greater
  50. than or equal to one and less than or equal to the value of
  51. {NGROUPS_MAX}+1.
  52. .SH "RETURN VALUE"
  53. Upon successful completion, the number of supplementary group IDs shall
  54. be returned. A return value of \-1 indicates failure and
  55. .IR errno
  56. shall be set to indicate the error.
  57. .SH ERRORS
  58. The
  59. \fIgetgroups\fR()
  60. function shall fail if:
  61. .TP
  62. .BR EINVAL
  63. The
  64. .IR gidsetsize
  65. argument is non-zero and less than the number of group IDs that would
  66. have been returned.
  67. .LP
  68. .IR "The following sections are informative."
  69. .SH EXAMPLES
  70. .SS "Getting the Supplementary Group IDs of the Calling Process"
  71. .P
  72. The following example places the current supplementary group IDs of the
  73. calling process into the
  74. .IR group
  75. array.
  76. .sp
  77. .RS 4
  78. .nf
  80. #include <sys/types.h>
  81. #include <unistd.h>
  82. \&...
  83. gid_t *group;
  84. int nogroups;
  85. long ngroups_max;
  86. .P
  87. ngroups_max = sysconf(_SC_NGROUPS_MAX) + 1;
  88. group = (gid_t *)malloc(ngroups_max *sizeof(gid_t));
  89. .P
  90. ngroups = getgroups(ngroups_max, group);
  91. .fi
  92. .P
  93. .RE
  94. .SH "APPLICATION USAGE"
  95. None.
  96. .SH RATIONALE
  97. The related function
  98. \fIsetgroups\fR()
  99. is a privileged operation and therefore is not covered by this volume of POSIX.1\(hy2017.
  100. .P
  101. As implied by the definition of supplementary groups, the effective
  102. group ID
  103. may appear in the array returned by
  104. \fIgetgroups\fR()
  105. or it may be returned only by
  106. \fIgetegid\fR().
  107. Duplication may exist, but the application needs to call
  108. \fIgetegid\fR()
  109. to be sure of getting all of the information. Various implementation
  110. variations and administrative sequences cause the set of groups
  111. appearing in the result of
  112. \fIgetgroups\fR()
  113. to vary in order and as to whether the effective group ID is included,
  114. even when the set of groups is the same (in the mathematical sense of
  115. ``set''). (The history of a process and its parents could affect the
  116. details of the result.)
  117. .P
  118. Application developers should note that
  119. {NGROUPS_MAX}
  120. is not necessarily a constant on all implementations.
  121. .SH "FUTURE DIRECTIONS"
  122. None.
  123. .SH "SEE ALSO"
  124. .IR "\fIgetegid\fR\^(\|)",
  125. .IR "\fIsetgid\fR\^(\|)"
  126. .P
  127. The Base Definitions volume of POSIX.1\(hy2017,
  128. .IR "\fB<sys_types.h>\fP",
  129. .IR "\fB<unistd.h>\fP"
  130. .\"
  131. .SH COPYRIGHT
  132. Portions of this text are reprinted and reproduced in electronic form
  133. from IEEE Std 1003.1-2017, Standard for Information Technology
  134. -- Portable Operating System Interface (POSIX), The Open Group Base
  135. Specifications Issue 7, 2018 Edition,
  136. Copyright (C) 2018 by the Institute of
  137. Electrical and Electronics Engineers, Inc and The Open Group.
  138. In the event of any discrepancy between this version and the original IEEE and
  139. The Open Group Standard, the original IEEE and The Open Group Standard
  140. is the referee document. The original Standard can be obtained online at
  141. http://www.opengroup.org/unix/online.html .
  142. .PP
  143. Any typographical or formatting errors that appear
  144. in this page are most likely
  145. to have been introduced during the conversion of the source files to
  146. man page format. To report such errors, see
  147. https://www.kernel.org/doc/man-pages/reporting_bugs.html .