diff options
Diffstat (limited to 'man-pages-posix-2013/man3p/tcsetattr.3p')
| -rw-r--r-- | man-pages-posix-2013/man3p/tcsetattr.3p | 240 |
1 files changed, 240 insertions, 0 deletions
diff --git a/man-pages-posix-2013/man3p/tcsetattr.3p b/man-pages-posix-2013/man3p/tcsetattr.3p new file mode 100644 index 0000000..014383b --- /dev/null +++ b/man-pages-posix-2013/man3p/tcsetattr.3p @@ -0,0 +1,240 @@ +'\" et +.TH TCSETATTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. + +.SH NAME +tcsetattr +\(em set the parameters associated with the terminal +.SH SYNOPSIS +.LP +.nf +#include <termios.h> +.P +int tcsetattr(int \fIfildes\fP, int \fIoptional_actions\fP, + const struct termios *\fItermios_p\fP); +.fi +.SH DESCRIPTION +The +\fItcsetattr\fR() +function shall set the parameters associated with the terminal referred +to by the open file descriptor +.IR fildes +(an open file descriptor associated with a terminal) from the +.BR termios +structure referenced by +.IR termios_p +as follows: +.IP " *" 4 +If +.IR optional_actions +is TCSANOW, the change shall occur immediately. +.IP " *" 4 +If +.IR optional_actions +is TCSADRAIN, the change shall occur after all output written to +.IR fildes +is transmitted. This function should be used when changing parameters +that affect output. +.IP " *" 4 +If +.IR optional_actions +is TCSAFLUSH, the change shall occur after all output written to +.IR fildes +is transmitted, and all input so far received but not read shall be +discarded before the change is made. +.P +If the output baud rate stored in the +.BR termios +structure pointed to by +.IR termios_p +is the zero baud rate, B0, the modem control lines shall no longer +be asserted. Normally, this shall disconnect the line. +.P +If the input baud rate stored in the +.BR termios +structure pointed to by +.IR termios_p +is 0, the input baud rate given to the hardware is the same as the +output baud rate stored in the +.BR termios +structure. +.P +The +\fItcsetattr\fR() +function shall return successfully if it was able to perform any of the +requested actions, even if some of the requested actions could not be +performed. It shall set all the attributes that the implementation +supports as requested and leave all the attributes not supported by +the implementation unchanged. If no part of the request can be honored, +it shall return \(mi1 and set +.IR errno +to +.BR [EINVAL] . +If the input and output baud rates differ and are a combination that is +not supported, neither baud rate shall be changed. A subsequent call to +\fItcgetattr\fR() +shall return the actual state of the terminal device (reflecting both +the changes made and not made in the previous +\fItcsetattr\fR() +call). The +\fItcsetattr\fR() +function shall not change the values found in the +.BR termios +structure under any circumstances. +.P +The effect of +\fItcsetattr\fR() +is undefined if the value of the +.BR termios +structure pointed to by +.IR termios_p +was not derived from the result of a call to +\fItcgetattr\fR() +on +.IR fildes ; +an application should modify only fields and flags defined by this volume of POSIX.1\(hy2008 +between the call to +\fItcgetattr\fR() +and +\fItcsetattr\fR(), +leaving all other fields and flags unmodified. +.P +No actions defined by this volume of POSIX.1\(hy2008, other than a call to +\fItcsetattr\fR(), +a close of the last file descriptor in the system associated with this +terminal device, or an open of the first file descriptor in the system +associated with this terminal device (using the O_TTY_INIT flag if it +is non-zero and the device is not a pseudo-terminal), shall cause any +of the terminal attributes defined by this volume of POSIX.1\(hy2008 to change. +.P +If +\fItcsetattr\fR() +is called from a process which is a member of a background process +group on a +.IR fildes +associated with its controlling terminal: +.IP " *" 4 +If the calling thread is blocking SIGTTOU signals or the process is +ignoring SIGTTOU signals, the operation completes normally and no signal +is sent. +.IP " *" 4 +Otherwise, a SIGTTOU signal shall be sent to the process group. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, +\(mi1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcsetattr\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINTR +A signal interrupted +\fItcsetattr\fR(). +.TP +.BR EINVAL +The +.IR optional_actions +argument is not a supported value, or an attempt was made to change an +attribute represented in the +.BR termios +structure to an unsupported value. +.TP +.BR EIO +The process group of the writing process is orphaned, the calling thread +is not blocking SIGTTOU, and the process is not ignoring SIGTTOU. +.TP +.BR ENOTTY +The file associated with +.IR fildes +is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If trying to change baud rates, applications should call +\fItcsetattr\fR() +then call +\fItcgetattr\fR() +in order to determine what baud rates were actually selected. +.P +In general, there are two reasons for an application to change the +parameters associated with a terminal device: +.IP " 1." 4 +The device already has working parameter settings but the application +needs a different behavior, such as non-canonical mode instead of +canonical mode. The application sets (or clears) only a few flags or +.IR c_cc [\^] +values. Typically, the terminal device in this case is either the +controlling terminal for the process or a pseudo-terminal. +.IP " 2." 4 +The device is a modem or similar piece of equipment connected by a serial +line, and it was not open before the application opened it. In this case, +the application needs to initialize all of the parameter settings ``from +scratch''. However, since the +.BR termios +structure may include both standard and non-standard parameters, the +application cannot just initialize the whole structure in an arbitrary +way (e.g., using +\fImemset\fR()) +as this may cause some of the non-standard parameters to be set +incorrectly, resulting in non-conforming behavior of the terminal +device. Conversely, the application cannot just set the standard +parameters, assuming that the non-standard parameters will already have +suitable values, as the device might previously have been used with +non-conforming parameter settings (and some implementations retain the +settings from one use to the next). The solution is to open the terminal +device using the O_TTY_INIT flag to initialize the terminal device to +have conforming parameter settings, obtain those settings using +\fItcgetattr\fR(), +and then set all of the standard parameters to the desired settings. +.SH RATIONALE +The +\fItcsetattr\fR() +function can be interrupted in the following situations: +.IP " *" 4 +It is interrupted while waiting for output to drain. +.IP " *" 4 +It is called from a process in a background process group and SIGTTOU +is caught. +.P +See also the RATIONALE section in +.IR "\fItcgetattr\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +Using an input baud rate of 0 to set the input rate equal to the output +rate may not necessarily be supported in a future version of this volume of POSIX.1\(hy2008. +.SH "SEE ALSO" +.IR "\fIcfgetispeed\fR\^(\|)", +.IR "\fItcgetattr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB<termios.h>\fP" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/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 . |