TPUT(1P)

✨ PROLOG ✨

okay bestie, real talk before we even start: this page is part of the POSIX Programmer's Manual, and the Linux implementation of this interface may differ (so like, go check the matching Linux manual page for the actual Linux tea), or honestly the interface might not even be implemented on Linux at all. 💀

---

💖 NAME 💖

tput — change terminal characteristics

---

🦋 SYNOPSIS 🦋

tput [-T type] operand...

---

🌸 DESCRIPTION 🌸

So tput is the utility that displays terminal-dependent information. How it actually retrieves that info? Unspecified, bestie. Not our problem, not specified.

Depending on which operand you hand it, the information displayed is gonna either clear the terminal screen, initialize the user's terminal, or reset the user's terminal. And the exact consequences of displaying that information? Also unspecified. We vibe, we don't over-explain. 💅

---

✨ OPTIONS ✨

tput shall conform to the Base Definitions volume of POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines. (Yes she follows the rules, she's a good girl.)

The following option shall be supported:

• -T type — say what type of terminal we're dealing with. If you don't pass this option and the TERM variable is unset or null, then an unspecified default terminal type gets used. Also important: the setting of type takes precedence over whatever's in TERM. 👑

---

🎀 OPERANDS 🎀

The following strings shall be supported as operands by the implementation in the POSIX locale:

• clear — display the clear-screen sequence. bye bye screen content 🫶
• init — display the sequence that initializes the user's terminal, in an implementation-defined manner.
• reset — display the sequence that resets the user's terminal, in an implementation-defined manner.

and like, if a terminal doesn't support any of the operations described by these operands? That is not an error condition. Not even a little. Don't stress. 🧚

---

🌈 STDIN 🌈

Not used. She doesn't read, she only serves. 💅

---

🍓 INPUT FILES 🍓

None. Nothing. Empty. Nada.

---

💜 ENVIRONMENT VARIABLES 💜

These variables shall affect the execution of tput:

• LANG — provides a default value for the internationalization variables that are unset or null. (Peep the Base Definitions volume of POSIX.1‐2017, Section 8.2, Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.)
• LC_ALL — if this is set to a non-empty string value, it overrides the values of all the other internationalization variables. she said "I'm in charge here".
• LC_CTYPE — determines the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as opposed to multi-byte characters in arguments).
• LC_MESSAGES — determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error.
• NLSPATH — determines the location of message catalogs for the processing of LC_MESSAGES.
• TERM — determines the terminal type. If this variable is unset or null, and if the -T option is not specified, then an unspecified default terminal type shall be used.

---

🌟 ASYNCHRONOUS EVENTS 🌟

Default. That's it. That's the whole section. iconic behaviour honestly.

---

⭐ STDOUT ⭐

If standard output is a terminal device, it may be used for writing the appropriate sequence to clear the screen or reset or initialize the terminal. 🎀

But if standard output is not a terminal device? Undefined results occur. so like, be careful bestie, that's the danger zone.

---

💀 STDERR 💀

The standard error shall be used only for diagnostic messages. It's not a chat channel, it's for yelling about problems.

---

🙈 OUTPUT FILES 🙈

None. zero. nothing to see here.

---

🦄 EXTENDED DESCRIPTION 🦄

None. she said "no extended description, I'm mysterious". 💅

---

🔥 EXIT STATUS 🔥

The following exit values shall be returned:

• 0 — the requested string was written successfully. slay! ✅
• 1 — unspecified. 😶
• 2 — usage error. you used it wrong, babe.
• 3 — no information is available about the specified terminal type. 😭
• 4 — the specified operand is invalid. that operand? not a real one.
• >4 — an error occurred. something happened, and it wasn't cute.

---

🌺 CONSEQUENCES OF ERRORS 🌺

If one of the operands is not available for the terminal, tput continues processing the remaining operands. she does not stop the whole show for one missing number. 💅

Heads up: the sections after this one are informative. Not the rules, just the commentary. 🎀

---

💖 APPLICATION USAGE 💖

The difference between resetting and initializing a terminal is left unspecified, because it varies greatly based on hardware types. In general though? Resetting is a more severe action. Like init is "wake up babe", reset is "wake up babe, you're at a party you don't remember". 😭

Some terminals use control characters to do the stated functions, and on those terminals it might make sense to use tput to store the initialization strings in a file or environment variable for later use. HOWEVER — because other terminals might rely on system calls to do this work, standard output cannot be used in a portable manner, like in the following non-portable constructs:

ClearVar=`tput clear`
tput reset | mailx -s "Wake Up" ddg

---

✨ EXAMPLES ✨

1. Initialize the terminal according to the type of terminal in the environmental variable TERM. This command can be included in a .profile file.

tput init

2. Reset a 450 terminal.

tput -T 450 reset

---

👑 RATIONALE 👑

The list of operands was reduced to a minimum for the following reasons:

• The only features chosen were those that were likely to be used by human users interacting with a terminal.
• Specifying the full terminfo set was not considered desirable, but the standard developers did not want to select among operands.
• This volume of POSIX.1‐2017 does not attempt to provide applications with sophisticated terminal handling capabilities, as that falls outside of its assigned scope and intersects with the responsibilities of other standards bodies. (she said "not my department, that's for other standards bodies, iykyk")

The difference between resetting and initializing a terminal is left unspecified as this varies greatly based on hardware types. In general, resetting is a more severe action. (yes we're saying it again, it's that important.)

The exit status of 1 is historically reserved for finding out if a Boolean operand is not set. Although the operands were reduced to a minimum, the exit status of 1 should still be reserved for the Boolean operands, for those sites that wish to support them.

---

🌈 FUTURE DIRECTIONS 🌈

None. the future is empty. manifesting nothing. 🧚

---

💜 SEE ALSO 💜

stty, tabs

The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines

---

🎀 COPYRIGHT 🎀

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

ok that's the whole page bestie!! this one's from IEEE/The Open Group, 2017 — yeah, 2017, she's vintage and still serving. 💖✨ go clear your screen and thrive. 🫶