1TCGETATTR(P)               POSIX Programmer's Manual              TCGETATTR(P)
2
3
4

NAME

6       tcgetattr - get the parameters associated with the terminal
7

SYNOPSIS

9       #include <termios.h>
10
11       int tcgetattr(int fildes, struct termios *termios_p);
12
13

DESCRIPTION

15       The  tcgetattr()  function shall get the parameters associated with the
16       terminal referred to by fildes and store them in the termios  structure
17       referenced  by termios_p.  The fildes argument is an open file descrip‐
18       tor associated with a terminal.
19
20       The termios_p argument is a pointer to a termios structure.
21
22       The tcgetattr() operation is allowed from any process.
23
24       If the terminal device supports different input and output baud  rates,
25       the  baud rates stored in the termios structure returned by tcgetattr()
26       shall reflect the actual baud rates, even if they are equal. If differ‐
27       ing  baud rates are not supported, the rate returned as the output baud
28       rate shall be the actual baud rate. If the  terminal  device  does  not
29       support  split  baud  rates,  the input baud rate stored in the termios
30       structure shall be the output rate (as one of the symbolic values).
31

RETURN VALUE

33       Upon successful completion, 0 shall be returned. Otherwise, -1 shall be
34       returned and errno set to indicate the error.
35

ERRORS

37       The tcgetattr() function shall fail if:
38
39       EBADF  The fildes argument is not a valid file descriptor.
40
41       ENOTTY The file associated with fildes is not a terminal.
42
43
44       The following sections are informative.
45

EXAMPLES

47       None.
48

APPLICATION USAGE

50       None.
51

RATIONALE

53       Care  must be taken when changing the terminal attributes. Applications
54       should always do a  tcgetattr(),  save  the  termios  structure  values
55       returned,  and  then  do  a  tcsetattr(),  changing  only the necessary
56       fields. The application should use the  values  saved  from  the  tcge‐
57       tattr() to reset the terminal state whenever it is done with the termi‐
58       nal. This is necessary because terminal attributes apply to the  under‐
59       lying  port and not to each individual open instance; that is, all pro‐
60       cesses that have used the terminal see the latest attribute changes.
61
62       A program that uses these functions should be written to catch all sig‐
63       nals and take other appropriate actions to ensure that when the program
64       terminates, whether planned or not,  the  terminal  device's  state  is
65       restored to its original state.
66
67       Existing  practice  dealing  with  error  returns  when  only part of a
68       request can be honored is based on calls to the  ioctl()  function.  In
69       historical  BSD and System V implementations, the corresponding ioctl()
70       returns zero if the requested actions were semantically  correct,  even
71       if  some  of  the  requested  changes  could not be made. Many existing
72       applications assume this behavior and would no longer work correctly if
73       the return value were changed from zero to -1 in this case.
74
75       Note that either specification has a problem. When zero is returned, it
76       implies everything succeeded even if some of the changes were not made.
77       When  -1  is returned, it implies everything failed even though some of
78       the changes were made.
79
80       Applications that need all of the requested changes made to work  prop‐
81       erly  should  follow tcsetattr() with a call to tcgetattr() and compare
82       the appropriate field values.
83

FUTURE DIRECTIONS

85       None.
86

SEE ALSO

88       tcsetattr() , the  Base  Definitions  volume  of  IEEE Std 1003.1-2001,
89       Chapter 11, General Terminal Interface, <termios.h>
90
92       Portions  of  this text are reprinted and reproduced in electronic form
93       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
94       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
95       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
96       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
97       event of any discrepancy between this version and the original IEEE and
98       The  Open Group Standard, the original IEEE and The Open Group Standard
99       is the referee document. The original Standard can be  obtained  online
100       at http://www.opengroup.org/unix/online.html .
101
102
103
104IEEE/The Open Group                  2003                         TCGETATTR(P)
Impressum