man3/tcgetpgrp.3

   1 .\" Copyright (C) 2002 Andries Brouwer <aeb@cwi.nl>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH TCGETPGRP 3 2021-03-22 "Linux man-pages (unreleased)"
   6 .SH NAME
   7 tcgetpgrp, tcsetpgrp \- get and set terminal foreground process group
   8 .SH LIBRARY
   9 Standard C library
  10 .RI ( libc ", " \-lc )
  11 .SH SYNOPSIS
  12 .nf
  13 .B "#include <unistd.h>"
  14 .PP
  15 .BI "pid_t tcgetpgrp(int " fd );
  16 .BI "int tcsetpgrp(int " fd ", pid_t " pgrp );
  17 .fi
  18 .SH DESCRIPTION
  19 The function
  20 .BR tcgetpgrp ()
  21 returns the process group ID of the foreground process group on the
  22 terminal associated to
  23 .IR fd ,
  24 which must be the controlling terminal of the calling process.
  25 .\" The process itself may be a background process.
  26 .PP
  27 The function
  28 .BR tcsetpgrp ()
  29 makes the process group with process group ID
  30 .I pgrp
  31 the foreground process group on the terminal associated to
  32 .IR fd ,
  33 which must be the controlling terminal of the calling process,
  34 and still be associated with its session.
  35 Moreover,
  36 .I pgrp
  37 must be a (nonempty) process group belonging to
  38 the same session as the calling process.
  39 .PP
  40 If
  41 .BR tcsetpgrp ()
  42 is called by a member of a background process group in its session,
  43 and the calling process is not blocking or ignoring
  44 .BR SIGTTOU ,
  45 a
  46 .B SIGTTOU
  47 signal is sent to all members of this background process group.
  48 .SH RETURN VALUE
  49 When
  50 .I fd
  51 refers to the controlling terminal of the calling process,
  52 the function
  53 .BR tcgetpgrp ()
  54 will return the foreground process group ID of that terminal
  55 if there is one, and some value larger than 1 that is not
  56 presently a process group ID otherwise.
  57 When
  58 .I fd
  59 does not refer to the controlling terminal of the calling process,
  60 \-1 is returned, and
  61 .I errno
  62 is set to indicate the error.
  63 .PP
  64 When successful,
  65 .BR tcsetpgrp ()
  66 returns 0.
  67 Otherwise, it returns \-1, and
  68 .I errno
  69 is set to indicate the error.
  70 .SH ERRORS
  71 .TP
  72 .B EBADF
  73 .I fd
  74 is not a valid file descriptor.
  75 .TP
  76 .B EINVAL
  77 .I pgrp
  78 has an unsupported value.
  79 .TP
  80 .B ENOTTY
  81 The calling process does not have a controlling terminal, or
  82 it has one but it is not described by
  83 .IR fd ,
  84 or, for
  85 .BR tcsetpgrp (),
  86 this controlling terminal is no longer associated with the session
  87 of the calling process.
  88 .TP
  89 .B EPERM
  90 .I pgrp
  91 has a supported value, but is not the process group ID of a
  92 process in the same session as the calling process.
  93 .SH ATTRIBUTES
  94 For an explanation of the terms used in this section, see
  95 .BR attributes (7).
  96 .ad l
  97 .nh
  98 .TS
  99 allbox;
 100 lbx lb lb
 101 l l l.
 102 Interface       Attribute       Value
 103 T{
 104 .BR tcgetpgrp (),
 105 .BR tcsetpgrp ()
 106 T}      Thread safety   MT-Safe
 107 .TE
 108 .hy
 109 .ad
 110 .sp 1
 111 .SH STANDARDS
 112 POSIX.1-2001, POSIX.1-2008.
 113 .SH NOTES
 114 These functions are implemented via the
 115 .B TIOCGPGRP
 116 and
 117 .B TIOCSPGRP
 118 ioctls.
 119 .SS History
 120 The ioctls appeared in 4.2BSD.
 121 The functions are POSIX inventions.
 122 .SH SEE ALSO
 123 .BR setpgid (2),
 124 .BR setsid (2),
 125 .BR credentials (7)