tcgetpgrp(3)

💅 tcgetpgrp — bestie edition (it's page 3 of the manual, section 3, iykyk)

okay so real talk, this is tcgetpgrp(3), living in the Library Functions Manual section of your friendly neighborhood man pages. two little functions about who's the main character on your terminal, and it's genuinely iconic. let's get into it 🎀

---

✨ NAME ✨

tcgetpgrp, tcsetpgrp — get and set terminal foreground process group

like. that's the whole job description. get it, set it. slay.

---

📚 LIBRARY 📚

Standard C library (libc, -lc)

---

🦋 SYNOPSIS 🦋

#include <unistd.h>

pid_t tcgetpgrp(int fd);
int tcsetpgrp(int fd, pid_t pgrp);

---

💖 DESCRIPTION 💖

okay so first up, tcgetpgrp(). she returns the process group ID of the foreground process group on the terminal associated to fd. and bestie, fd must be the controlling terminal of the calling process. no controlling terminal, no vibes. periodt.

then we have tcsetpgrp(), the setter of the duo. she makes the process group with process group ID pgrp the foreground process group on the terminal associated to fd. requirements, and I'm not being dramatic, these are the requirements:

• fd must be the controlling terminal of the calling process,
• that terminal must still be associated with its session,
• and pgrp must be a (nonempty) process group belonging to the same session as the calling process.

and then the little spicy bit 💀 — if tcsetpgrp() is called by a member of a background process group in its session, and the calling process is not blocking or ignoring SIGTTOU, then a SIGTTOU signal gets sent to all members of this background process group. so like, know that before you go poking around. not a drill.

---

🫶 RETURN VALUE 🫶

so when fd refers to the controlling terminal of the calling process, tcgetpgrp() will return the foreground process group ID of that terminal if there is one, and otherwise it returns some value larger than 1 that is not presently a process group ID. yes, genuinely. that's what it does. that's not a typo, that's just the API being quirky.

and when fd does not refer to the controlling terminal of the calling process? -1 is returned, and errno is set to indicate the error. rude but fair.

for tcsetpgrp(): when successful, she returns 0. otherwise -1, and errno is set to indicate the error. standard queen behavior.

---

😭 ERRORS 😭

• EBADF — fd is not a valid file descriptor. bestie that's not a file 😭
• EINVAL — pgrp has an unsupported value.
• ENOTTY — the calling process does not have a controlling terminal, or it has one but it is not described by fd, or, for tcsetpgrp(), this controlling terminal is no longer associated with the session of the calling process.
• EPERM — pgrp has a supported value, but is not the process group ID of a process in the same session as the calling process. valid but not your session. rejected 💅

---

🔥 ATTRIBUTES 🔥

for an explanation of the terms used in this section, go see attributes(7). the receipts:

• Interface: tcgetpgrp(), tcsetpgrp() — Attribute: Thread safety — Value: MT-Safe

so yeah. MT-Safe. she's safe to share with the group chat. 🌈

---

⭐ VERSIONS ⭐

these functions are implemented via the TIOCGPGRP and TIOCSPGRP ioctls. that's the machinery under the hood, no cap.

---

👑 STANDARDS 👑

POSIX.1-2008. she's certified, she's official, she's standards-compliant.

---

🌸 HISTORY 🌸

POSIX.1-2001.

the ioctls appeared in 4.2BSD. the functions are POSIX inventions. so the vibes are old-school BSD, but the actual functions got invented by POSIX. a true glow-up origin story.

---

🧚 SEE ALSO 🧚

• setpgid(2)
• setsid(2)
• credentials(7)

---

okay bye bestie, go forth and manage your foreground process groups responsibly — this has been Linux man-pages version 6.20, dated 2026-02-08, and honestly? she ate. mwah 💜🎀✨