Manpage of SAMESTR

SAMESTR

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

NAME

SAMESTR - test for STREAMS pipe or fifo

SYNOPSIS

#include <sys/stream.h>

int SAMESTR(q);

ARGUMENTS

q: the queue to compare against the next queue.

INTERFACE

STREAMS.

DESCRIPTION

SAMESTR() tests whether the next queue belongs to the same stream as the specified queue q. SAMESTR() can be used to detect whether or not q belongs to a pipe(4) or a fifo(4).

USAGE

SAMESTR() is not normally used by drivers or modules. Although it can be used by a module to detect the midpoint of a STREAMS-based pipe(4) or fifo(4), it is not often done.

RETURN

SAMESTR() returns true (1) if the next queue from the specified queue, q->q_next, belongs to the same stream (read or write) as the specified queue q. In this case, the queue q is above the midpoint of a pipe(4) or fifo(4).

SAMESTR() returns false (0) if the next queue from the specified queue, q->q_next, belongs to a different stream (read or write) as the specified queue q. In this case, the queue q is above the midpoint of a pipe(4) or fifo(4).

SAMESTR() also returns false (0) if the next queue from the specified queue, q->q_next, is NULL. In this case, the queue q is a stream end (stream head or driver).

ERRORS

When SAMESTR() fails, it returns zero (0). SAMESTR() fails when the queue pointer q->q_next is NULL.

CONTEXT

SAMESTR() can be called from any context, including user context, module procedures, call-outs, callbacks, soft interrupts (tasklets and bottom halves), and interrupt service routines.

MP-STREAMS

SAMESTR() is MP-safe; however, the caller is responsible for the validity of the reference q. References to q from a procedure, call-out or callback predicated on the queue pair to which q belongs are guaranteed valid. The caller must guarantee validity from call-outs, callbacks, soft interrupts and interrupt service routines not predicated on the queue pair to which q belongs.

NOTICES

If the passed in queue pointer, q, is invalid, the result is undefined.

If the passed in queue pointer, q, is NULL, a kernel panic may occur.

BUGS

SAMESTR() has no known bugs.

COMPATIBILITY

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

---: SAMESTR() is defined for UnixWare®[2], Solaris®[3], HP-UX®[4], SUPER-UX®[5], LiS[6]. These systems also support STREAMS-based pipe(4) and fifo(4).
---: SAMESTR() may be called on a stream frozen with freezestr(9). SVR 4.2 MP DDI/DKI[1], Solaris®[3], SUPER-UX®[5] and UnixWare®[2] do not permit SAMESTR() to be called on a stream frozen with freezestr(9). This is presumably because UnixWare® and Solaris® allows frozen streams to manipulate the q->q_next pointers directly. HP-UX® on the other hand, does not allow q->q_next pointers to be manipulated directly and provides the weldq(9) function to perform that action. Portable STREAMS drivers and modules should not call bcanputnext() on a stream frozen with freezestr(9).
---: HP-UX®[4] lists SAMESTR() as a function that can only be passed a queue in the queue pair currently being synchronized within a module procedure. HP-UX®[4] also lists SAMESTR() 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 SAMESTR() from outside of a qinit(9) routine for the queue pair of q.
---: SAMESTR() is not defined for AIX®[7], OSF/1®[8], UXP/V®[9]. These systems do not support STREAMS-based pipe(4) and fifo(4).
---: SAMESTR() is not very useful on systems that do not support STREAMS-based pipe(4) or fifo(4).
---: Linux Fast-STREAMS supports STREAMS-based pipe(4) and fifo(4).
---: Because the size and members of the queue(9) structure vary from implementation to implementation, binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

SVR 4.2 MP DDI/DKI[1]

HISTORY

SAMESTR() first appeared in SVR 4.0 STREAMS[10].

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]: UnixWare® 7.1.3, UnixWare® 7 STREAMS Programmer's Guide, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[3]: Solaris® 8, STREAMS Programming Guide, August 1999, (Palo Alto, California), Sun Microsystems, Inc., Sun. [Part No: 805-7478-05] <http://docs-pdf.sun.com/>
[4]: 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/>
[5]: SUPER-UX® Release 9.2, SUPER-UX STREAMS Programmers Guide, 1999, NEC Corporation, NEC.
[6]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[7]: AIX® 5L Version 5.1, AIX STREAMS Programmers Guide, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[8]: 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/>
[9]: UXP/V® V10L10, UXP/V Programmer's Guide: STREAMS V10, 1997, Fujitsu Limited, Fujitsu.
[10]: SVR 4, UNIX® System V Release 4 STREAMS Programmer's Guide, 1990, (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.

Index

NAME
SYNOPSIS
ARGUMENTS
INTERFACE
DESCRIPTION
USAGE
RETURN
ERRORS
CONTEXT
MP-STREAMS
NOTICES
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

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