unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 modem(7)							    modem(7)




 NAME
      modem - asynchronous serial modem line control

 SYNOPSIS
      #include <&lt&lt&lt;sys/modem.h>&gt&gt&gt;

 DESCRIPTION
      This section describes the two modes of modem line control and the
      three types of terminal port access.  It also discusses the effect of
      the bits of the termio structure that affect modem line control.	The
      modem related ioctl(2) system calls are discussed at the end of the
      document.

    Definitions
      There are several terms that are used within the following discussion
      which will be defined here for reference.	 ``Modem control lines''
      (CONTROL) are generally defined as those outgoing modem lines that are
      automatically controlled by the driver.  ``Modem status lines''
      (STATUS) are generally defined as those incoming modem lines that are
      automatically monitored by the driver.  CONTROL and STATUS for a
      terminal file vary according to the modem line control mode of the
      file (see Modem line control modes below).  An open(2) to a port will
      be considered to be BLOCKED if it is waiting for another file on the
      same port to be closed.  An open to a port is considered to be PENDING
      if it is waiting for the STATUS to be raised.  An open to a port is
      considered to be SUCCESSFUL if the open system call has returned to
      the calling process without error.

    Open flag bits
      Currently, the only open flag bits recognized by the driver is the
      O_NDELAY and O_NONBLOCK bits.  When either of these bits is set, an
      open call to the driver will never become blocked.  If possible, the
      open will be returned immediately as SUCCESSFUL, and the driver will
      continue the process of opening the tty file.  If it is not possible,
      then the open will be returned immediately with the appropriate error
      code as described in the appropriate section.

    Termio bits
      When set, the CLOCAL bit in the termios or termio structure (see
      termio(7)) is used to remove the driver's automatic monitoring of the
      modem lines.  However, the user's ability to control the modem lines
      is determined only by the mode in effect and does not depend on the
      state of CLOCAL.	Normally, the driver will monitor and require the
      STATUS to be raised.  An open system call will raise the CONTROL and
      wait for the STATUS before completing unless the CLOCAL bit is set.
      (If the O_NDELAY or O_NONBLOCK bit is set, the open will be returned
      immediately, but the driver will otherwise continue to monitor the
      modem lines as normal based on the state of the CLOCAL bit.) Normally,
      loss of the STATUS will cause the driver to break the modem connection
      and lower the CONTROL.  However, if CLOCAL is set, any changes in the
      STATUS will be ignored.  A connection is required before any data may



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 modem(7)							    modem(7)




      be read or written, unless CLOCAL is set.	 Any timers that would
      normally be in effect (see Modem line control modes and Modem timers
      below) will be stopped while CLOCAL is set.

      When the CLOCAL bit is changed from clear to set, the driver will
      assume the existence of an active device (such as a modem) on the port
      regardless of the STATUS.	 If any of the CONTROL are raised at that
      point in time, they will continue in that state.	The STATUS will no
      longer be actively monitored.  When the CLOCAL bit is changed from set
      to clear, the driver will resume actively monitoring the STATUS.	If
      all of the CONTROL and STATUS are raised at that point in time, the
      driver will continue the modem connection.  If any of the STATUS are
      not raised, the driver will act as though those signals were lost (as
      described in Modem line control modes below) and, if the device is a
      controlling terminal, a hangup signal will be sent to the controlling
      process.	If any of the CONTROL are not raised, the driver will break
      the modem connection by lowering all the CONTROL.

      The HUPCL bit in the termios or termio structure determines the action
      of the driver regarding the CONTROL when the last close system call is
      issued to a terminal file.  If the HUPCL bit is set, the driver will
      lower the CONTROL at close time and the modem connection will be
      broken.  If HUPCL is not set and a modem connection exists, it will
      continue to exist, even after the close is issued.  The driver will
      not change the CONTROL.

    Terminal port access types
      There are three types of modem access: call-in connections, call-out
      connections, and direct (no modem control) connections.  A given port
      may be accessed through all three types of connection by accessing
      different files.	The modem access type of a terminal file is
      determined by the file's major and/or minor device numbers.

      The call-in type of access is used when the connection is expected to
      be established by an incoming call.  This is the type that would be
      used by getty(1M) to accept logins over a modem.	When an open is
      issued to such a file, the driver may wait for an incoming call and
      will then raise the CONTROL based on the current mode (see below) of
      the port.	 When the port is closed, the driver may or may not lower
      the CONTROL depending on the HUPCL bit.

      The call-out type of access is used when the connection is expected to
      be established by an outgoing call.  This would be used by programs
      such as uucp(1).	When an open is issued to such a file, the driver
      will immediately raise the CONTROL and wait for a connection based on
      the mode currently in effect.  When the port is closed, the driver may
      or may not lower the CONTROL depending on the HUPCL bit.

      The direct type of access is used when no driver modem control is
      desired.	This could then be used for directly connected terminals
      that use a three-wire connection, or to talk to a modem before a



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 modem(7)							    modem(7)




      connection has been established.	The second case allows a program to
      give dialing instructions to the modem.  Neither the CLOCAL nor the
      HUPCL bits have any effect on a port accessed through a direct file.
      (However, both bits may be inherited by other types of files; see
      Terminal port access interlock below.) An open to a direct file does
      not affect the CONTROL and does not depend on any particular state of
      the STATUS to succeed.  When the file is closed, the driver will not
      affect the state of the CONTROL.	If a modem connection has been
      established, it will continue to exist.  Setting the speed of a direct
      file to B0 (see termio(7) ) will be considered an impossible speed
      change and will be ignored.  It will not affect the CONTROL.

    Modem line control modes
      There are two modes of modem line control: CCITT mode and simple mode.
      A given port may have only one of these two modes in effect at any
      given point in time.  An attempt to open a port with a mode other than
      the one in effect (from a PENDING or SUCCESSFUL open on a different
      file) will cause the open to be returned with an ENXIO error.  The
      modem access type of a terminal file is determined by the file's major
      and/or minor device numbers.

      CCITT mode is used for connections to switched line modems.  The
      CONTROL for CCITT mode are Data Terminal Ready (DTR) and Request to
      Send (RTS).  The STATUS are Data Set Ready (DSR), Data Carrier Detect
      (DCD), and Clear to Send (CTS).  Additionally, the Ring Indicator (RI)
      signal indicates the presence of an incoming call.  When a connection
      is begun (an incoming call for a call-in file or an open issued to a
      call-out file), the CONTROL are raised and a connection timer (see
      Modem timers below) is started.  If the STATUS become raised before
      the time period has elapsed, a connection is established and the open
      request is returned successfully.	 If the time period expires, the
      CONTROL are lowered and the connection is aborted.  For a call-in
      file, the driver will wait for another incoming call; for a call-out
      file, the open will be returned with an EIO error.  Once a connection
      is established, loss of either DSR or CTS will cause the CONTROL to be
      lowered and, if the device is a controlling terminal, a hangup signal
      will be sent to the controlling process.

      If DCD is lost, a timer is started.  If DCD resumes before the time
      period has expired, the connection will be maintained.  However, no
      data transfer will occur during this time.  The driver will stop
      transmitting characters, and any characters received by the driver
      will be discarded.  (However, on some implementations data
      transmission cannot be stopped.  See DEPENDENCIES.) If DCD is not
      restored within the allotted time, the connection will be broken as
      described above for DSR and CTS.

      If the modem connection is to be broken when the close system call is
      issued (i.e.  HUPCL is set), then the CONTROL will be lowered and the
      close will be returned as successful.  However, no further opens will
      be allowed until after both DSR and CTS have been lowered by the



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 modem(7)							    modem(7)




      modem, and the hangup timer (see Modem timers below) has expired.	 The
      action taken in response to an open during this time will be the same
      as if the port were still open.  (See Terminal port access interlock
      below.)

      When a port is in CCITT mode, the driver has complete control of the
      modem lines and the user is not allowed to change the setting of the
      CONTROL or affect which STATUS are actively monitored by the driver
      (see Modem ioctls below).	 This is to provide strict adherence with
      the CCITT recommendations.

      Simple mode is used for connections to devices which require only a
      simple method of modem line control.  This can include devices such as
      black boxes, data switches, or for system-to-system connections.	It
      can also be used with modems which cannot operate under the CCITT
      recommendations.	The CONTROL for simple mode consists of only DTR.
      The STATUS consists of only DCD.	When an open is issued, the CONTROL
      is raised but no connection timer is started.  When the STATUS becomes
      raised, a connection is established and the open request is returned
      as SUCCESSFUL.  Once a connection is established, loss of the STATUS
      will cause the CONTROL to be lowered and, if the device is a
      controlling terminal, a hangup signal will be sent to the controlling
      process.

      When a port is in simple mode, the driver will normally control the
      modem lines.  However, the user is allowed to change the setting of
      the CONTROL (see Modem ioctls below).

    Terminal port access interlock
      An interlock mechanism is provided between the three access types of
      terminal files.  It prevents more than one file from being
      successfully opened at a time, but allows certain opens to succeed
      while others are PENDING so that a port can be opened through a call-
      out connection while getty has a pending open at a call-in connection.
      The three access types are given a priority that determines which open
      will succeed if more than one file has an open issued against it.	 The
      three access types are ordered from lowest priority to highest as
      follows: call-in, call-out, and direct.

      If an open is issued to a port which already has a SUCCESSFUL open on
      it of a lower priority type, the new open will be returned with an
      EBUSY error.  (EBUSY will also be returned by an attempted open on a
      CCITT call-out file if an incoming call indication is currently being
      received.	 In this case, if there is a PENDING open on the
      corresponding CCITT call-in file, this PENDING open will complete.) If
      the lower priority open is PENDING, the new open will succeed if
      possible, or will be left PENDING if waiting for the STATUS and the
      lower priority open will become BLOCKED.	If a higher priority open
      has succeeded or is PENDING, the new open will be BLOCKED, unless the
      new open has the O_NDELAY flag bit set, in which case the open will be
      returned with an EBUSY error.  Once an open on one type of file is



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 modem(7)							    modem(7)




      SUCCESSFUL, any PENDING opens on lower priority files will become
      BLOCKED.

      When a file of one priority is closed, a BLOCKED open on the next
      lower priority type file will become active.  If all of the STATUS are
      raised, the open will be SUCCESSFUL, otherwise the open will become
      PENDING waiting for the STATUS.  If the lower priority open is
      SUCCESSFUL (because the connection was maintained when the higher
      priority file was closed), the port characteristics (speed, parity,
      etc.) that were set by the higher priority file will be inherited by
      the lower priority file.	If the connection is not maintained through
      the close, the port characteristics will be set to default values.

    Modem timers
      There are four timers currently defined for use with modem
      connections.  The first three of the timers are applicable only to
      CCITT mode connections.  In general, the effect of changing a timer
      value while the timer is running is system dependent.  However,
      setting the timer value to zero is guaranteed to disable the timer
      even if it is running.

      The connect timer is used to limit the amount of time to wait for a
      connection to be established once it has been begun.  This timer is
      started when an incoming call has been received on a call-in file, or
      when an open has been issued on a call-out file for which no opens are
      already pending.	If the connection is completed in time, the timer is
      aborted.	If the time period expires, the connection is aborted.	For
      a call-in file, the driver will again wait for an incoming call and
      the open will remain pending.  For a call-out file, the open will be
      returned with an EIO error.

      The carrier detect timer is used to limit the amount of time to wait
      before causing a disconnect if DCD drops.	 If carrier is not re-
      established in this time, a disconnect will occur.  If carrier is re-
      established before the timeout, the timer will be aborted and the
      connection maintained.  During the period when carrier is not raised,
      no data will be transferred across the line.

      The no activity timer is used to limit the amount of time a connection
      will remain open with no data transfer across the line.  When the data
      line becomes quiescent with no data transfer, this timer will be
      started.	If data is again transferred over the line in either
      direction before the time limit, the timer will be aborted.  If no
      activity occurs before the timeout has occurred, the driver will
      disconnect the line.  This can be used to avoid long and costly
      telephone connections when data transfer has been stopped either
      normally or abnormally.

      The last timer defined, the hangup timer, is used for both CCITT and
      simple modes.  This timer controls the amount of time to wait after
      disconnecting a modem line before allowing another open.	This time



 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000






 modem(7)							    modem(7)




      period should be made long enough to guarantee that the connection has
      been terminated by the telephone switching equipment.  If this period
      is not long enough, the telephone connection may not be broken and a
      succeeding open may complete with the old connection.

    HP-UX Modem ioctls
      Several ioctl system calls apply to manipulation of modem lines.	They
      use the following information defined in <&lt&lt&lt;sys/modem.h>&gt&gt&gt;:

	   #define  NMTIMER   6
	   typedef  unsigned  long   mflag;
	   struct   mtimer     {
		    unsigned  short  m_timers[NMTIMER];
		    };

      Each bit of the mflag long corresponds to one of the modem lines as
      follows:

	   MRTS	  Request to Send	outbound
	   MCTS	  Clear to Send		inbound
	   MDSR	  Data Set Ready	inbound
	   MDCD	  Data Carrier Detect	inbound
	   MDTR	  Data Terminal Ready	outbound
	   MRI	  Ring Indicator	inbound
	   MDRS	  Data Rate Select	outbound

      The timer values are defined in the array m_timers.  The relative
      position of the timer and default initial values and units for each
      timer are as follows:

	   0   MTCONNECT      25 s
	   1   MTCARRIER      400 ms
	   2   MTNOACTIVITY   0 min
	   3   MTHANGUP	      250 ms
	   4   Reserved
	   5   Reserved

      A value of zero for any timer will disable that timer.

      The modem line ioctl system calls have the form:

	   int ioctl(int fildes, int command, mflag *arg);

      The commands using this form are:

      MCGETA	     Get the current state of both inbound and outbound
		     modem lines and store in the mflag long referenced by
		     arg.  A raised line will be indicated by a one bit in
		     the appropriate position.





 Hewlett-Packard Company	    - 6 -   HP-UX Release 11i: November 2000






 modem(7)							    modem(7)




      MCSETA	     Set the outbound modem lines from the mflag long
		     referenced by arg.	 Setting an outbound bit to one
		     causes that line to be raised and zero to be lowered.
		     Setting bits for inbound lines has no effect.  Setting
		     any bits while in CCITT mode has no effect.  The change
		     to the modem lines is immediate and using this form
		     while characters are still being output may cause
		     unpredictable results.

      MCSETAW	     Wait for the output to drain and set the new parameters
		     as described above.

      MCSETAF	     Wait for the output to drain, then flush the input
		     queue and set the new parameters as described above.

      The timer value ioctl system calls have the form:

	   int ioctl(int fildes, int command, mtimer *arg);

      The commands using this form are:

      MCGETT	     Get the current timer value settings and store in the
		     mtimer structure referenced by arg.

      MCSETT	     Set the timer values from the structure referenced by
		     arg.

      For any timer, setting the timer value to its previous value has no
      effect.

    SVID3 Modem ioctls
      System V Interface Definition, Third Edition (SVID3) specifies
      additional ioctl system calls to manipulate the modem lines.  They use
      information defined in <&lt&lt&lt;termios.h>&gt&gt&gt;.

      Each ioctl passes an integer argument in which each of the following
      bit definitions correspond to one of the modem lines as follows:

	   TIOCM_RTS   Request to Send	     outbound
	   TIOCM_CTS   Clear to Send	     inbound
	   TIOCM_DSR   Data Set Ready	     inbound
	   TIOCM_CAR   Data Carrier Detect   inbound
	   TIOCM_DTR   Data Terminal Ready   outbound
	   TIOCM_RNG   Ring Indicator	     inbound

      Additionally, TIOCM_CD is equivalent to TIOCM_CAR, and TIOCM_RI is
      equivalent to TIOCM_RNG.

      The modem line ioctl system calls have the form:





 Hewlett-Packard Company	    - 7 -   HP-UX Release 11i: November 2000






 modem(7)							    modem(7)




	   int ioctl(int fildes, int command, int *arg);

      The commands using this form are:

      TIOCMGET	     Get the current state of both inbound and outbound
		     modem lines and store in the int referenced by arg.  A
		     raised line will be indicated by a one bit in the
		     appropriate position.

      TIOCMSET	     Set the outbound modem lines from the int referenced by
		     arg.

      TIOCMBIS	     Raise the control lines specified by a one in the
		     corresponding bit positions of the int referenced by
		     arg.

      TIOCMBIC	     Lower the control lines specified by a one in the
		     corresponding bit positions of the int referenced by
		     arg.

      Note that setting bits for inbound lines has no effect, and setting
      any bits while in CCITT mode has no effect.  Also, the change to the
      modem lines is immediate and using these ioctl's while characters are
      still being output may cause unpredictable results.

 WARNING
      Occasionally it is possible that a process may open a call-out file at
      approximately the same time as an incoming call is received.  In some
      cases, the call-out connection may be satisfied by the incoming call.
      In general, however, the results are indeterminate.  If necessary, the
      situation can be avoided by the use of two modems and ports, one for
      call-out connections and the other for receiving incoming calls.

 DEPENDENCIES
      Some hardware implementations may not have access to all modem lines
      supported by MCSETA.  If a particular hardware does not support a
      given line, attempts to set the value of a line will be ignored, and
      reading the current state of the line will return zero.  The
      appropriate I/O card manual should be referenced to determine the
      lines supported by the hardware installed.

      Some hardware implementations may not have access to all timers
      supported by MCSETT.  Also, the granularity of the individual timers
      may vary depending on the hardware and system in use.  The effect of
      setting a timer out of range or with a granularity outside the
      capability of a particular system should be documented by that system.
      The effect of changing the value for a timer while that timer is
      running is system dependent and should be documented by each system.

      Setting the CLOCAL bit while a timer is running will cause the timer
      to be stopped.  It is a system dependency whether or not the timer is



 Hewlett-Packard Company	    - 8 -   HP-UX Release 11i: November 2000






 modem(7)							    modem(7)




      restarted, and if so, the value at which it is restarted when the
      CLOCAL bit is subsequently cleared.

      On those implementations supporting the HP27140A 6-Channel
      Multiplexer, transmission of characters cannot be stopped during loss
      of DCD.  The driver cannot detect loss of DCD until the connection is
      broken.  Also, the I/O card may still have characters in its internal
      buffers and will still try to transmit them.

 AUTHOR
      modem was developed by HP and AT&T.

 FILES
      /dev/cua*
      /dev/cul*
      /dev/tty*
      /dev/ttyd*

      EISA mux has adopted the following device files naming convention:

	   /dev/<&lt&lt&lt;cua|cul|tty|ttyd>&gt&gt&gt;<&lt&lt&lt;Instance_Number>&gt&gt&gt;<&lt&lt&lt;Port_Module_Name>&gt&gt&gt;<&lt&lt&lt;Port_Number>&gt&gt&gt;

      where Port_Module_Name = [a..h], Port_Number = 1-16

      For example: /dev/cua2a1, /dev/cul2b8, /dev/tty2g12, /dev/ttyd2h16

 SEE ALSO
      stty(1), mknod(1M), ioctl(2), open(2), termio(7).


























 Hewlett-Packard Company	    - 9 -   HP-UX Release 11i: November 2000