man/man3/tcgetpgrp.3

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