diff options
Diffstat (limited to 'man3p/cfgetispeed.3p')
-rw-r--r-- | man3p/cfgetispeed.3p | 106 |
1 files changed, 106 insertions, 0 deletions
diff --git a/man3p/cfgetispeed.3p b/man3p/cfgetispeed.3p new file mode 100644 index 000000000..9c7952d9c --- /dev/null +++ b/man3p/cfgetispeed.3p @@ -0,0 +1,106 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CFGETISPEED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" cfgetispeed +.SH NAME +cfgetispeed \- get input baud rate +.SH SYNOPSIS +.LP +\fB#include <termios.h> +.br +.sp +speed_t cfgetispeed(const struct termios *\fP\fItermios_p\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIcfgetispeed\fP() function shall extract the input baud rate +from the \fBtermios\fP structure to which the +\fItermios_p\fP argument points. +.LP +This function shall return exactly the value in the \fBtermios\fP +data structure, without interpretation. +.SH RETURN VALUE +.LP +Upon successful completion, \fIcfgetispeed\fP() shall return a value +of type \fBspeed_t\fP representing the input baud +rate. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The term "baud" is used historically here, but is not technically +correct. This is properly "bits per second", which may not +be the same as baud. However, the term is used because of the historical +usage and understanding. +.LP +The \fIcfgetospeed\fP(), \fIcfgetispeed\fP(), \fIcfsetospeed\fP(), +and \fIcfsetispeed\fP() +functions do not take arguments as numbers, but rather as symbolic +names. There are two reasons for this: +.IP " 1." 4 +Historically, numbers were not used because of the way the rate was +stored in the data structure. This is retained even though a +function is now used. +.LP +.IP " 2." 4 +More importantly, only a limited set of possible rates is at all portable, +and this constrains the application to that set. +.LP +.LP +There is nothing to prevent an implementation accepting as an extension +a number (such as 126), and since the encoding of the +Bxxx symbols is not specified, this can be done to avoid introducing +ambiguity. +.LP +Setting the input baud rate to zero was a mechanism to allow for split +baud rates. Clarifications in this volume of +IEEE\ Std\ 1003.1-2001 have made it possible to determine whether +split rates are supported and to support them without +having to treat zero as a special case. Since this functionality is +also confusing, it has been declared obsolescent. The 0 +argument referred to is the literal constant 0, not the symbolic constant +B0. This volume of IEEE\ Std\ 1003.1-2001 does +not preclude B0 from being defined as the value 0; in fact, implementations +would likely benefit from the two being equivalent. +This volume of IEEE\ Std\ 1003.1-2001 does not fully specify whether +the previous \fIcfsetispeed\fP() value is retained after a \fItcgetattr\fP() +as the actual value or as zero. Therefore, conforming applications +should +always set both the input speed and output speed when setting either. +.LP +In historical implementations, the baud rate information is traditionally +kept in \fBc_cflag\fP. Applications should be written +to presume that this might be the case (and thus not blindly copy +\fBc_cflag\fP), but not to rely on it in case it is in some +other field of the structure. Setting the \fBc_cflag\fP field absolutely +after setting a baud rate is a non-portable action +because of this. In general, the unused parts of the flag fields might +be used by the implementation and should not be blindly +copied from the descriptions of one terminal device to another. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcfgetospeed\fP() , \fIcfsetispeed\fP() , \fIcfsetospeed\fP() , +\fItcgetattr\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 . |