Manpage of M_SIG

M_SIG

Section: Linux Fast-STREAMS DDI/DKI (9)
Updated: 2008-10-31
Index Return to Main Contents

NAME

M_SIG - STREAMS signal message

FORMAT

The M_SIG message block is a datab(9) structure and associated data buffer that contains structured data.

An M_SIG message is a normal priority message that consists of a single M_SIG message block.

The M_SIG message block contains a single unsigned char number indicating the signal number (defined in <sys/signal.h>), to be delivered to the process or process group.

INTERFACE

STREAMS.

DESCRIPTION

The M_SIG message is a normal priority message that is generated by a driver or module and sent upstream to the Stream head, requesting that a signal be posted to a process or process group.

The format of the M_SIG message is a single M_SIG message block containing in its first, and only, byte, the signal number (as defined in <sys/signal.h>) to be posted.

The M_SIG message is one of four message types, M_DATA(9), M_PROTO(9), M_PASSFP(9), and M_SIG, that are placed on the Stream head read queue by the Stream head read-side qi_putp(9) procedure. This means that the M_SIG message is not processed by the Stream head until the M_SIG message is at the head of the Stream head read queue, and a process makes an attempt to read from the queue (using system call such as read(2s), readv(2s), getmsg(2), getpmsg(2s), or a read-like ioctl(2s)).

When the M_SIG message is processed by the Stream head as part of a read operation, the Stream head examines the signal number contained in sole byte of the message. If the signal number contained in the message is {SIGPOLL}, the {SIGPOLL} signal will be posted to each process that registered for the S_MSG event using the I_SETSIG(7) command to ioctl(2s). If the signal number contained in the message is not {SIGPOLL}, then the signal is posted to the process group, if any, associated with the Stream.

Once the Stream head posts the signal to any process or process group meeting the criteria above, it frees the message.

In contrast, the M_PCSIG(9) message will generate a signal directly from the Stream head read queue qi_putp(9) procedure.

M_SIG messages cannot be generated directly by a user level process. M_SIG messages are consumed by the Stream head. M_SIG messages arriving at a non-multiplexing driver can be discarded (ignored and freed). M_SIG messages can be generated by drivers and modules.

USAGE

M_SIG can be used by a driver or module to generate a signal to a process within the message stream toward the Stream head. The signal can be used to signal processes immediately before an important service interface message will be read from the Stream. M_SIG can be used to alert processes waiting on POLLMSG in poll(2s), registered for S_MSG with I_SETSIG(7), or within a process group of a terminal, controlling terminal, or socket. The next read operation (e.g, getpmsg(2s)) performed by the alerted process will read the service interface message following the M_SIG. The use of M_SIG in this fashion, is normally detailed as part of the service interface definition for the module or driver.

Guidelines for processing of the M_SIG message are as follows:

*: Intermediate modules receiving the M_SIG message must pass it along the Stream in either the upstream or downstream in accordance with the procedure for normal priority messages: that is, the message is subject to flow control and must be ordered with respect to other normal priority messages on the queue. (This supports, for example, passing the M_SIG message across a STREAMS-based pipe(4).)
*: Non-multiplexing drivers receiving an M_SIG message will discard it.
*: Multiplexing drivers may pass the message to another queue. (This supports, for example, passing the M_SIG message across a STREAMS-based pseudo-terminal master/slave pair.)

NOTICES

Note that a process group is normally associated with a Stream under the following conditions:

(1): The Stream is a controlling terminal. A Stream becomes a controlling terminal if, during an open of the terminal using the open(2s) system call, a module or the driver sends a M_SETOPTS(9) message to the Stream head with the SO_ISTTY flag set in the so_flags member of the structure contained in the M_SETOPTS(9) message. In this case, if the opening process does not already have a controlling terminal, the Stream head assigns the terminal as a controlling terminal and sets the process group of the Stream to be the to be process group of the opening process. The process group can later be changed using the TIOCSPGRP [see termios(7)] command to ioctl(2s).
(2): The Stream is a terminal, but not a controlling terminal, and the process group was set against the Stream by a process with the TIOCSPGRP [see termios(7)] command to ioctl(2s), anyway.
(3): The Stream corresponds to a Socket, and the process group was set against the Socket by a process with the SIOCSPGRP [see sockios(7)] command to ioctl(2s).

Note also that the M_SIG message is not the proper way to post {SIGHUP}: {SIGHUP} should be sent to the session leader instead of the process group for a controlling terminal. To post a {SIGHUP} to the session leader for a controlling terminal, use the M_HANGUP(9) message instead.

COMPATIBILITY

The M_SIG STREAMS message is compatible with SVR 4.2 MP STREAMS, and implementations based on SVR 4, with the following portability considerations:

---: Linux Fast-STREAMS[1] also implements the Linux extended POLLSIG event to poll(2s), and the POSIX/SUSv3[2] POLL_SIG code for the siginfo structure described in sigaction(2) and signal.h(0p). As it is a GNU/Linux extension, it is not obvious how POLLSIG should work with STREAMS.
: Portable STREAMS applications wil not use the GNU/Linux POLLMSG extension: that is, they will not set it in the requested events against any file descriptor in the call to poll(2s).
---: M_SIG has a different constant value on older versions of OSF/1®[3], and older versions of LiS[4].
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS[1] instead of LiS[4].
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP STREAMS[5].

HISTORY

The M_SIG message first appeared in SVR 3[6].

REFERENCES

[1]: streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[2]: SUS Version 3, Single UNIX Specification, OpenGroup, Open Group Publication. <http://www.opengroup.org/onlinepubs/>
[3]: Digital® UNIX (OSF/1.2), Digital UNIX: Network Programmers Guide, 1996, (Palo Alto, California), Digital Equipment Corporation, Hewlett-Packard Company. <http://www.true64unix.compaq.com/docs/>
[4]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[5]: SVR 4.2, STREAMS Programmer's Guide, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[6]: SVR 3, UNIX® System V Release 3 STREAMS Programmer's Guide, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

TRADEMARKS

OpenSS7tm: is a trademark of OpenSS7 Corporation.
Linux®: is a registered trademark of Linus Torvalds.
UNIX®: is a registered trademark of The Open Group.
Solaris®: is a registered trademark of Sun Microsystems.

Other trademarks are the property of their respective owners.

IDENTIFICATION

Linux Fast-STREAMS: Package streams version 0.9.2.4 released 2008-10-31.

This document was created by man2html, using the manual pages.
Time: 17:21:35 GMT, May 23, 2013