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