👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for setpgid (linux section 3posix)

SETPGID(P)			    POSIX Programmer's Manual			       SETPGID(P)

NAME
       setpgid - set process group ID for job control

SYNOPSIS
       #include <unistd.h>

       int setpgid(pid_t pid, pid_t pgid);

DESCRIPTION
       The setpgid() function shall either join an existing process group or create a new process
       group within the session of the calling process. The process group ID of a session  leader
       shall  not  change. Upon successful completion, the process group ID of the process with a
       process ID that matches pid shall be set to pgid. As a special case,  if  pid  is  0,  the
       process ID of the calling process shall be used. Also, if pgid is 0, the process ID of the
       indicated process shall be used.

RETURN VALUE
       Upon successful completion, setpgid() shall return 0; otherwise, -1 shall be returned  and
       errno shall be set to indicate the error.

ERRORS
       The setpgid() function shall fail if:

       EACCES The  value  of  the  pid	argument matches the process ID of a child process of the
	      calling process and the child process has successfully executed  one  of	the  exec
	      functions.

       EINVAL The  value  of the pgid argument is less than 0, or is not a value supported by the
	      implementation.

       EPERM  The process indicated by the pid argument is a session leader.

       EPERM  The value of the pid argument matches the process ID of  a  child  process  of  the
	      calling  process	and  the  child process is not in the same session as the calling
	      process.

       EPERM  The value of the pgid argument is valid but does not match the process  ID  of  the
	      process  indicated by the pid argument and there is no process with a process group
	      ID that matches the value of the pgid argument in the same session as  the  calling
	      process.

       ESRCH  The  value of the pid argument does not match the process ID of the calling process
	      or of a child process of the calling process.

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       None.

RATIONALE
       The setpgid() function shall group processes together for the purpose of signaling, place-
       ment in foreground or background, and other job control actions.

       The  setpgid()  function  is similar to the setpgrp() function of 4.2 BSD, except that 4.2
       BSD allowed the specified new process group to assume any  value.  This	presents  certain
       security problems and is more flexible than necessary to support job control.

       To  provide  tighter security, setpgid() only allows the calling process to join a process
       group already in use inside its session or create a new process group whose process  group
       ID was equal to its process ID.

       When  a job control shell spawns a new job, the processes in the job must be placed into a
       new process group via setpgid(). There are two timing constraints involved in this action:

	1. The new process must be placed in the new process group before the appropriate program
	   is launched via one of the exec functions.

	2. The new process must be placed in the new process group before the shell can correctly
	   send signals to the new process group.

       To address these constraints, the following actions are performed.  The new processes call
       setpgid()  to  alter their own process groups after fork() but before exec. This satisfies
       the first constraint. Under 4.3 BSD, the second constraint is satisfied	by  the  synchro-
       nization  property  of  vfork();  that is, the shell is suspended until the child has com-
       pleted the exec, thus ensuring that the child has completed the setpgid(). A  new  version
       of  fork()  with  this  same  synchronization  property was considered, but it was decided
       instead to merely allow the parent shell process to adjust the process group of its  child
       processes via setpgid(). Both timing constraints are now satisfied by having both the par-
       ent shell and the child attempt to adjust the process group of the child process; it  does
       not matter which succeeds first.

       Since  it  would  be confusing to an application to have its process group change after it
       began executing (that is, after exec), and because the child process  would  already  have
       adjusted its process group before this, the [EACCES] error was added to disallow this.

       One  non-obvious  use of setpgid() is to allow a job control shell to return itself to its
       original process group (the one in effect when the job control shell was executed). A  job
       control shell does this before returning control back to its parent when it is terminating
       or suspending itself as a way of restoring its job control "state" back to what its parent
       would  expect.  (Note  that  the original process group of the job control shell typically
       matches the process group of its parent, but this is not necessarily always the case.)

FUTURE DIRECTIONS
       None.

SEE ALSO
       exec()  ,  getpgrp()  ,	setsid()  ,  tcsetpgrp()  ,  the  Base	Definitions   volume   of
       IEEE Std 1003.1-2001, <sys/types.h>, <unistd.h>

COPYRIGHT
       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2003 Edition, Standard for Information Technology  --  Portable	Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
       the Institute of Electrical and Electronics Engineers, Inc and  The  Open  Group.  In  the
       event  of  any  discrepancy  between this version and the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				       SETPGID(P)


All times are GMT -4. The time now is 07:42 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password