diff options
Diffstat (limited to 'man3p/tcgetattr.3p')
| -rw-r--r-- | man3p/tcgetattr.3p | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/man3p/tcgetattr.3p b/man3p/tcgetattr.3p new file mode 100644 index 000000000..cd2253720 --- /dev/null +++ b/man3p/tcgetattr.3p @@ -0,0 +1,109 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TCGETATTR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" tcgetattr +.SH NAME +tcgetattr \- get the parameters associated with the terminal +.SH SYNOPSIS +.LP +\fB#include <termios.h> +.br +.sp +int tcgetattr(int\fP \fIfildes\fP\fB, struct termios *\fP\fItermios_p\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItcgetattr\fP() function shall get the parameters associated +with the terminal referred to by \fIfildes\fP and store +them in the \fBtermios\fP structure referenced by \fItermios_p\fP. +The \fIfildes\fP argument is an open file descriptor +associated with a terminal. +.LP +The \fItermios_p\fP argument is a pointer to a \fBtermios\fP structure. +.LP +The \fItcgetattr\fP() operation is allowed from any process. +.LP +If the terminal device supports different input and output baud rates, +the baud rates stored in the \fBtermios\fP structure +returned by \fItcgetattr\fP() shall reflect the actual baud rates, +even if they are equal. If differing baud rates are not +supported, the rate returned as the output baud rate shall be the +actual baud rate. If the terminal device does not support split +baud rates, the input baud rate stored in the \fBtermios\fP structure +shall be the output rate (as one of the symbolic +values). +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned. Otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fItcgetattr\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B ENOTTY +The file associated with \fIfildes\fP is not a terminal. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +Care must be taken when changing the terminal attributes. Applications +should always do a \fItcgetattr\fP(), save the +\fBtermios\fP structure values returned, and then do a \fItcsetattr\fP(), +changing only +the necessary fields. The application should use the values saved +from the \fItcgetattr\fP() to reset the terminal state whenever +it is done with the terminal. This is necessary because terminal attributes +apply to the underlying port and not to each individual +open instance; that is, all processes that have used the terminal +see the latest attribute changes. +.LP +A program that uses these functions should be written to catch all +signals and take other appropriate actions to ensure that +when the program terminates, whether planned or not, the terminal +device's state is restored to its original state. +.LP +Existing practice dealing with error returns when only part of a request +can be honored is based on calls to the \fIioctl\fP() function. In +historical BSD and System V implementations, the corresponding \fIioctl\fP() +returns zero if the requested actions were semantically correct, even +if some of the +requested changes could not be made. Many existing applications assume +this behavior and would no longer work correctly if the +return value were changed from zero to -1 in this case. +.LP +Note that either specification has a problem. When zero is returned, +it implies everything succeeded even if some of the changes +were not made. When -1 is returned, it implies everything failed even +though some of the changes were made. +.LP +Applications that need all of the requested changes made to work properly +should follow \fItcsetattr\fP() with a call to \fItcgetattr\fP() and +compare the appropriate field +values. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fItcsetattr\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +Chapter 11, General Terminal Interface, \fI<termios.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 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 . |