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

setpgid.3p (6304B)


  1. '\" et
  2. .TH SETPGID "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. setpgid
  12. \(em set process group ID for job control
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. int setpgid(pid_t \fIpid\fP, pid_t \fIpgid\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIsetpgid\fR()
  23. function shall either join an existing process group or create a
  24. new process group within the session of the calling process.
  25. .P
  26. The process group ID of a session leader shall not change.
  27. .P
  28. Upon successful completion, the process group ID of the process with
  29. a process ID that matches
  30. .IR pid
  31. shall be set to
  32. .IR pgid .
  33. .P
  34. As a special case, if
  35. .IR pid
  36. is 0, the process ID of the calling process shall be used. Also, if
  37. .IR pgid
  38. is 0, the process ID of the indicated process shall be used.
  39. .SH "RETURN VALUE"
  40. Upon successful completion,
  41. \fIsetpgid\fR()
  42. shall return 0; otherwise, \-1 shall be returned and
  43. .IR errno
  44. shall be set to indicate the error.
  45. .SH ERRORS
  46. The
  47. \fIsetpgid\fR()
  48. function shall fail if:
  49. .TP
  50. .BR EACCES
  51. The value of the
  52. .IR pid
  53. argument matches the process ID of a child process of the calling
  54. process and the child process has successfully executed one of the
  55. .IR exec
  56. functions.
  57. .TP
  58. .BR EINVAL
  59. The value of the
  60. .IR pgid
  61. argument is less than 0, or is not a value supported by the
  62. implementation.
  63. .TP
  64. .BR EPERM
  65. The process indicated by the
  66. .IR pid
  67. argument is a session leader.
  68. .TP
  69. .BR EPERM
  70. The value of the
  71. .IR pid
  72. argument matches the process ID of a child process of the calling
  73. process and the child process is not in the same session as the calling
  74. process.
  75. .TP
  76. .BR EPERM
  77. The value of the
  78. .IR pgid
  79. argument is valid but does not match the process ID of the process
  80. indicated by the
  81. .IR pid
  82. argument and there is no process with a process group ID that matches
  83. the value of the
  84. .IR pgid
  85. argument in the same session as the calling process.
  86. .TP
  87. .BR ESRCH
  88. The value of the
  89. .IR pid
  90. argument does not match the process ID of the calling process or of a
  91. child process of the calling process.
  92. .LP
  93. .IR "The following sections are informative."
  94. .SH EXAMPLES
  95. None.
  96. .SH "APPLICATION USAGE"
  97. None.
  98. .SH RATIONALE
  99. The
  100. \fIsetpgid\fR()
  101. function shall group processes together for the purpose of
  102. signaling, placement in foreground or background,
  103. and other job control actions.
  104. .P
  105. The
  106. \fIsetpgid\fR()
  107. function is similar to the
  108. \fIsetpgrp\fR()
  109. function of 4.2 BSD, except that 4.2 BSD allowed the specified new process
  110. group to assume any value. This presents certain security problems and
  111. is more
  112. flexible than necessary to support job control.
  113. .P
  114. To provide tighter security,
  115. \fIsetpgid\fR()
  116. only allows the calling process to join a process group already in use
  117. inside its session or create a new process group
  118. whose process group ID was equal to its process ID.
  119. .P
  120. When a job control shell spawns a new job, the processes in the
  121. job must be placed into a new process group via
  122. \fIsetpgid\fR().
  123. There are two timing constraints involved in this action:
  124. .IP " 1." 4
  125. The new process must be placed in the new process group before the
  126. appropriate program is launched via one of the
  127. .IR exec
  128. functions.
  129. .IP " 2." 4
  130. The new process must be placed in the new process group before the
  131. shell can correctly send signals to the new process group.
  132. .P
  133. To address these constraints, the following actions are performed. The
  134. new processes call
  135. \fIsetpgid\fR()
  136. to alter their own process groups after
  137. \fIfork\fR()
  138. but before
  139. .IR exec .
  140. This satisfies the first constraint. Under 4.3 BSD, the second
  141. constraint is satisfied by the synchronization property of
  142. .IR vfork (\|);
  143. that is, the shell is suspended until the child has completed the
  144. .IR exec ,
  145. thus ensuring that the child has completed the
  146. \fIsetpgid\fR().
  147. A new version of
  148. \fIfork\fR()
  149. with this same synchronization property was considered, but it was
  150. decided instead to merely allow the parent shell process to adjust the
  151. process group of its child processes via
  152. \fIsetpgid\fR().
  153. Both timing constraints are now satisfied by having both the parent
  154. shell and the child attempt to adjust the process group of the child
  155. process; it does not matter which succeeds first.
  156. .P
  157. Since it would be confusing to an application to have its process
  158. group change after it began executing (that is, after
  159. .IR exec ),
  160. and because the child process would already have adjusted its process
  161. group before this, the
  162. .BR [EACCES]
  163. error was added to disallow this.
  164. .P
  165. One non-obvious use of
  166. \fIsetpgid\fR()
  167. is to allow a job control shell to return itself to its original
  168. process group (the one in effect when the job control shell was
  169. executed). A job control shell does this before returning control back
  170. to its parent when it is terminating or suspending itself as a way of
  171. restoring its job control ``state'' back to what its parent would
  172. expect. (Note that the original process group of the job control shell
  173. typically matches the process group of its parent, but this is not
  174. necessarily always the case.)
  175. .SH "FUTURE DIRECTIONS"
  176. None.
  177. .SH "SEE ALSO"
  178. .IR "\fIexec\fR\^",
  179. .IR "\fIgetpgrp\fR\^(\|)",
  180. .IR "\fIsetsid\fR\^(\|)",
  181. .IR "\fItcsetpgrp\fR\^(\|)"
  182. .P
  183. The Base Definitions volume of POSIX.1\(hy2017,
  184. .IR "\fB<sys_types.h>\fP",
  185. .IR "\fB<unistd.h>\fP"
  186. .\"
  187. .SH COPYRIGHT
  188. Portions of this text are reprinted and reproduced in electronic form
  189. from IEEE Std 1003.1-2017, Standard for Information Technology
  190. -- Portable Operating System Interface (POSIX), The Open Group Base
  191. Specifications Issue 7, 2018 Edition,
  192. Copyright (C) 2018 by the Institute of
  193. Electrical and Electronics Engineers, Inc and The Open Group.
  194. In the event of any discrepancy between this version and the original IEEE and
  195. The Open Group Standard, the original IEEE and The Open Group Standard
  196. is the referee document. The original Standard can be obtained online at
  197. http://www.opengroup.org/unix/online.html .
  198. .PP
  199. Any typographical or formatting errors that appear
  200. in this page are most likely
  201. to have been introduced during the conversion of the source files to
  202. man page format. To report such errors, see
  203. https://www.kernel.org/doc/man-pages/reporting_bugs.html .