Content-type: text/html Man page of setpgid

setpgid

Section: System Calls (2)
Index Return to Main Contents
 

NAME

setpgid, setpgrp - Sets the process group ID  

SYNOPSIS

#include <unistd.h>

int setpgid(
        pid_t process_id,
        pid_t process_group_id);

pid_t setpgrp(void);

Application developers may want to specify an #include statement for <sys/types.h> before the one for <unistd.h> if programs are being developed for multiple platforms. The additional #include statement is not required on Tru64 UNIX systems or by ISO or X/Open standards, but may be required on other vendors' systems that conform to these standards.

[Digital]  The following alternate declaration for setpgrp() does not conform to current standards and is supported only for backward compatibility:

int setpgrp(
        pid_t process_id,
        pid_t process_group_id);  

STANDARDS

Interfaces documented on this reference page conform to industry standards as follows:

setpgid():  XPG4, XPG4-UNIX

setpgrp():  XPG4-UNIX, SVID 3

Refer to the standards(5) reference page for more information about industry standards and associated tags.  

PARAMETERS

Specifies the ID of the process whose process group ID is to be changed. Specifies the new process group ID.  

DESCRIPTION

Use the setpgid() function to add a process to an existing process group or to create a new process group within a process's session. The setpgid() function does not change the process group ID of a session leader.

The setpgid() function sets the process group ID of the process identified by the process_id parameter. The process group ID is set to the value specified in the process_group_id parameter.

If the process_id parameter contains 0 (zero), the setpgid() function sets the process group ID of the calling process. The new value of the process group ID is the one specified in the process_group_id parameter.

If the process_group_id parameter contains 0 (zero), the setpgid() function sets the process group ID of the specified process using the process group ID of the calling process. The specified process is the one identified by the process_id parameter.

The setpgid() function supports job control.

The setpgrp() function sets the process group ID of the calling process to be equal to the process ID of the calling process. If the function creates a new session, the new session has no controlling terminal. This function does not change the process group ID of a session leader.  

NOTES

[Digital]  When compiled in the X/Open UNIX environment, calls to the setpgrp() function are internally renamed by prepending _E to the function name. When you are debugging a module that includes the setpgrp() function and for which _XOPEN_SOURCE_EXTENDED has been defined, use _Esetpgrp to refer to the setpgrp() call. See standards(5) for further information.

[Digital]  The backward-compatible version of the setpgrp() function is supported for use outside of the System V habitat or X/Open-UNIX environment. This version of setpgrp() behaves like the setpgid() function. In this case, you specify a process ID and process group ID as parameters in the call to setpgrp(). The setpgrp() function does not change the process group ID of a session leader.  

RETURN VALUES

Upon successful completion, the setpgid() function returns a value of 0 (zero). Otherwise, the function returns a value of -1 and sets errno to indicate the error.

Upon successful completion, the setpgrp() function returns the new process group ID.

[Digital]  The alternate version of setpgrp() returns a value of 0 (zero) on successful completion. Otherwise, the function returns a value of -1 and sets errno to indicate the error.  

ERRORS

The setpgid() function sets errno to the specified values for the following conditions: The value of the process_id parameter matches the process ID of a child process of the calling process and the child process has successfully executed one of the exec() functions. The value of the process_group_id parameter is less than or equal to 0 (zero), or is not a valid process ID. The value of the process_group_id parameter is a valid process ID, but that process is not in the same session as the calling process. The process indicated by the process_id parameter is a session leader.

The value of the process_id parameter 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.
The value of the process_group_id parameter is valid but does not match the process ID of the process indicated by the process_id parameter, and there is no process with a process group ID that matches the value of the process_group_id parameter in the same session as the calling process. The value of the process_id parameter does not match the process ID of the calling process or of a child process of the calling process.

No errors are defined for the standard version of the setpgrp() function.

[Digital]  The backward-compatible version of setpgrp() sets errno to the same values as setpgid().  

RELATED INFORMATION

Functions: exec(2), fork(2), getpid(2), getsid(2), kill(2)

Standards: standards(5)

Guides:  Programmer's Guide delim off


 

Index

NAME
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
NOTES
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:40:18 GMT, October 02, 2010