lib/libc/sys/getpgrp.2

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)getpgrp.2   8.1 (Berkeley) 6/4/93
  29 .\"
  30 .Dd June 4, 1993
  31 .Dt GETPGRP 2
  32 .Os
  33 .Sh NAME
  34 .Nm getpgrp
  35 .Nd get process group
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In unistd.h
  40 .Ft pid_t
  41 .Fn getpgrp void
  42 .Ft pid_t
  43 .Fn getpgid "pid_t pid"
  44 .Sh DESCRIPTION
  45 The process group of the current process is returned by
  46 .Fn getpgrp .
  47 The process group of the process identified by
  48 .Fa pid
  49 is returned by
  50 .Fn getpgid .
  51 If
  52 .Fa pid
  53 is zero,
  54 .Fn getpgid
  55 returns the process group of the current process.
  56 .Pp
  57 Process groups are used for distribution of signals, and
  58 by terminals to arbitrate requests for their input: processes
  59 that have the same process group as the terminal are foreground
  60 and may read, while others will block with a signal if they attempt
  61 to read.
  62 .Pp
  63 This system call is thus used by programs such as
  64 .Xr csh 1
  65 to create
  66 process groups
  67 in implementing job control.
  68 The
  69 .Fn tcgetpgrp
  70 and
  71 .Fn tcsetpgrp
  72 calls
  73 are used to get/set the process group of the control terminal.
  74 .Sh RETURN VALUES
  75 The
  76 .Fn getpgrp
  77 system call always succeeds.
  78 Upon successful completion, the
  79 .Fn getpgid
  80 system call returns the process group of the specified process;
  81 otherwise, it returns a value of \-1 and sets
  82 .Va errno
  83 to indicate the error.
  84 .Sh COMPATIBILITY
  85 This version of
  86 .Fn getpgrp
  87 differs from past Berkeley versions by not taking a
  88 .Fa "pid_t pid"
  89 argument.
  90 This incompatibility is required by
  91 .St -p1003.1-90 .
  92 .Pp
  93 From the
  94 .St -p1003.1-90
  95 Rationale:
  96 .Pp
  97 .Bx 4.3
  98 provides a
  99 .Fn getpgrp
 100 system call that returns the process group ID for a specified process.
 101 Although this function is used to support job control, all known
 102 job-control shells always specify the calling process with this
 103 function.
 104 Thus, the simpler
 105 .At V
 106 .Fn getpgrp
 107 suffices, and the added complexity of the
 108 .Bx 4.3
 109 .Fn getpgrp
 110 has been omitted from POSIX.1.
 111 The old functionality is available from the
 112 .Fn getpgid
 113 system call.
 114 .Sh ERRORS
 115 The
 116 .Fn getpgid
 117 system call
 118 will succeed unless:
 119 .Bl -tag -width Er
 120 .It Bq Er ESRCH
 121 there is no process whose process ID equals
 122 .Fa pid
 123 .El
 124 .Sh SEE ALSO
 125 .Xr getsid 2 ,
 126 .Xr setpgid 2 ,
 127 .Xr termios 4
 128 .Sh STANDARDS
 129 The
 130 .Fn getpgrp
 131 system call is expected to conform to
 132 .St -p1003.1-90 .
 133 .Sh HISTORY
 134 The
 135 .Fn getpgrp
 136 system call appeared in
 137 .Bx 4.0 .
 138 The
 139 .Fn getpgid
 140 system call is derived from its usage in
 141 .At V.4 .