Description: Manual Page

Keywords: ss7 ss7/ip ss7 over ip ss7 mtp ss7 sccp ss7 tcap sigtran mtp sccp tcap openss7 acb56 linux telephony pstn linux telephony linux nebs linux compactpci

---

PUTNEXT

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

---

NAME

putnext - put a message on the downstream STREAMS message queue

SYNOPSIS

#include <sys/stream.h>

void putnext(queue_t *q, mblk_t *mp);

ARGUMENTS

q

the queue beyond which to put the message.

mp

the message to put beyond the queue.

INTERFACE

STREAMS.

DESCRIPTION

putnext() invokes the q->q_next->q_info->qi_putp qi_putp(9) procedure of the queue q->q_next with the message pointed to by mp.

putnext() is normally invoked from within the qi_putp(9) or qi_srvp(9) procedure belonging to queue q.

It is the responsibility of a procedure calling putnext() with a normal message pointed to by mp to first call canputnext(9) or bcanputnext(9) for the queue to check for flow control. If canputnext(9) or bcanputnext(9) fails for queue q, the procedure should not normally invoke putnext() with a low priority message for the flow controlled queue q->q_next.

putnext() will wake up any processes waiting with qwait(9) or qwait_sig(9) on the next queue, q->q_next.

RETURN

putnext() returns void.

ERRORS

putnext() fails silently when a queue band structure cannot be allocated for the band specified in mp->b_band. The caller can ensure that a queue band structure exists for the band in quest by calling strqset(9) for the band.

CONTEXT

putnext() can be called from any context, including user context, module procedures, callouts, callbacks, soft interrupts (tasklets and bottom halves), and interrupt service routines. Consideration must be given when calling putnext() from interrupt service routine context that the next module in the Stream might not be prepared to be called at interrupt service routine context.

MP-STREAMS

putnext() is MP-safe; however, the caller must ensure exclusive access to the passed in message, mp. The driver or module qi_putp(9) procedure invoked must also be MP-safe. Under Linux Fast-STREAMS any put(9) procedure can be executed concurrently with any queue qi_qopen(9), qi_qclose(9), qi_putp(9), qi_srvp(9) procedure, esbbcall(9), bufcall(9), qbufcall(9), timeout(9), qtimeout(9), callback function, software interrrupt, tasklet, bottom half, or interrupt service routine. Either the driver or module must be synchronized using STREAMS synchronization levels, or the qi_putp(9) procedure itself must perform its own mutual exclusion.

SEE ALSO

putq(9), canputnext(9), bcanputnext(9), freezestr(9), unfreezestr(9), qi_qopen(9), qi_qclose(9), qi_putp(9), qi_srvp(9), esbbcall(9), bufcall(9), qbufcall(9), timeout(9), qtimeout(9).

BUGS

putnext() has no known bugs.

COMPATIBILITY

putnext() is compatible with SVR 4.2 MP DDI/DKI[1], and implementations based on SVR 4[2] with the following portability considerations:

---

putnext() results are undefined if the arguments q or mp is invalid. Under LiS, putnext() fails silently if q->q_next has a q_info pointer of NULL; the queue pointed to by q->q_next has no qi_putp(9) procedure; or the queue pointed to by q->q_next is closing, or the queue has had qi_putp(9) and qi_srvp(9) procedure processing turned off (e.g. with qprocsoff(9)).

---

putnext() is MP-safe across pushes and pops of modules and other Stream reconfiguration because it protects dereference of the q->q_next pointer with the Stream head read lock. Under LiS, putnext() simply calls put() with the q->q_next pointer.

---

HP-UX®[3] lists putnext() as a function that can only be passed a queue in the queue pair currently being synchronized within a module procedure. HP-UX®[3] also lists putnext() as a utility that cannot be called from user functions or non-STREAMS code; that is, contexts asynchronous to the Stream containing q.

HP-UX® compatible drivers and modules will not call putnext() from outside of a qinit(9) routine for the queue pair of q.

---

put(9), putnext(), qreply(9) will invoke a queue's qi_putp(9) procedure shared and multi-threaded.

This is equivalent to Solaris® drivers with the D_MP flag set or with the D_MTPUTSHARED flag set.

LiS holds an exclusive nesting queue procedures lock while calling putnext() executes. LiS lis_safe_putnext() and lis_safe_qreply(9) call the lis_safe_putmsg(9) function, meaning that all message passing functions in LiS lock out interrupts until the entire thread of execution completes. LiS drivers and modules calling putnext() should notice superior interrupt service routine latency and performance. It is normally the case that qi_putp(9) procedures are MP-safe as they normally use only MP-safe queue and message utility functions. Also, most qi_putp(9) procedures are inherently invoked single threaded (from a single-threaded qi_srvp(9) procedure). Lack of locking should not present a problem.

Because LiS also uses this lock for qi_srvp(9) procedures, this means that while the LiS scheduler is running (at kernel thread priority 50), interrupts, timeouts, bottom halves, hi tasklets and soft interrupts are indefinitely postponed. This is not acceptable for soft real-time performance. Rewrite LiS qi_putp(9) procedures to be MP-safe.

---

UnixWare®[4] and SUPER-UX®[5] do not permit putnext() to be called on a Stream frozen with freezestr(9).

Portable STREAMS drivers and modules will not call putnext() on a Stream frozen by the caller with freezestr(9).

---

Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP DDI/DKI[1].

HISTORY

putnext() appears as part of SVR 4.0 STREAMS[6].

putnext() first appeared in SVR 3[7]. In SVR 3, SVR 4 and SVR 4.2, putnext() returned int[1,2,7].

REFERENCES

[1]

USL DDI/DKI, Device Driver Interface/Driver-Kernel Interface (DDI/DKI) Reference Manual for Intel Processors, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

[2]

SVR 4 DDI/DKI, UNIX® System V Release 4 Device Driver Interface/Driver-Kernel Interface (DDI/DKI) Reference Manual, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

[3]

HP-UX STREAMS, STREAMS Programmer's Guide -- HP 9000 and Integrity Server Computer Systems, October 2005, (Palo Alto, California), Hewlett-Packard Development Company L.P., HP. <http://docs.hp.com/>

[4]

UnixWare® 7.1.3, UnixWare® 7 STREAMS Programmer's Guide, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>

[5]

SUPER-UX® Release 9.2, SUPER-UX STREAMS Programmers Guide, 1999, NEC Corporation, NEC.

[6]

SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

[7]

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.

Copyright©1997-2008OpenSS7 Corp. All Rights Reserved.
(See roff source for permission notice.)

---

Index

NAME

SYNOPSIS

ARGUMENTS

INTERFACE

DESCRIPTION

RETURN

ERRORS

CONTEXT

MP-STREAMS

SEE ALSO

BUGS

COMPATIBILITY

CONFORMANCE

HISTORY

REFERENCES

TRADEMARKS

IDENTIFICATION

---

This document was created by man2html, using the manual pages.
Time: 21:25:47 GMT, May 21, 2013