Appendix C

Utilities

C.1 COMMAND LIST

C.2 COMMAND PAGE FORMAT

NAME

command name - function/purpose

command name   options

Shows command invocation and the required syntax.

Describes the function and uses of the command. Options and arguments, operating states, and other command information are provided in this section.

Illustrates command usage.

Lists related commands and documents.

adjmsg - trim bytes from a message

#include <sys/stream.h>
int adjmsg(mblk_t*mp, int len);

adjmsg removes bytes from a message.

Arguments:

mp

Pointer to the message to be trimmed.

len

The number of bytes to be removed.

 
 

Return Values:

If the message can be trimmed successfully, 1 is returned. Otherwise, 0 is returned.
 

Usage:

|len| (the absolute value of len) specified how many bytes are to be removed. If len is greater than 0, bytes are removed from the head of the message. If len is less than 0, bytes are removed from the tail. adjmsg fails if |len| is greater than the number of bytes in mp. If len spans more than one message block in the message, the messages blocks must be the same type, or else adjmsg will fail.

If len is greater than the amount of data in a single message block, that message block is not freed. Rather, it is left linked in the message, and its read and write pointers are set equal to each other, indicating no data present in the block.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep.

Driver-defined mask locks and simple locks may be held across calls to this function.

msgb(D4)

NAME

allocb - allocate a message block

#include <sys/types.h>
#include <sys/stream.h>

mblk_t *allocb(int size, uint_t pri);

allocb tries to allocate a STREAMS message block.

Arguments:

size

The number of bytes in the message block.

pri

 Priority of the request.

 

One of the following three values can be selected for this priority: BPRI_LO, BPRI_MED, or BPRI_HI.

 

Return Values:

If successful, allocb returns a pointer to the allocated message block of type M_DATA (defined in sys/stream.h). If a block cannot be allocated, a NULL pointer is returned.
 

Usage:

Buffer allocation fails only when the system is out of memory. If no buffer is available, the bufcall(D3) function can help a module recover from an allocation failure.

The following figure identifies the data structure members that are affected when a message block is allocated.

 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

NAME

bcanput - test for flow control in a specified priority band

 

#include <sys/types.h>
#include <sys/stream.h>

int bcanput(queue_t *q, uchar_t pri);

Like the canput(D3) function, bcanput searches through the stream (starting at q) until it finds a queue containing a service routine, or until it reaches the end of the stream. If found, the queue containing the service routine is tested to see if a message of priority pri can be enqueued. If the band is full, bcanput marks the queue to automatically back-enable the caller's service routine when the amount of data in messages on the queue has reached its low water mark.
 

Arguments:

q

Pointer to the message queue.

pri

Message priority.

 

Return Values:

bcanput returns 1 if a message of priority pri can be sent in the stream, or 0 if the priority band is flow-controlled. If bcanput reaches the end of the stream without finding a queue with a service routine, then it returns 1.
 

Usage:

The driver is responsible for both testing a queue with bcanput and refraining from placing a message on the queue if bcanput fails.

It is possible because of race conditions to test for room using bcanput and get an indication that there is room for a message, and then have the queue fill up before subsequently enqueuing the message, causing a violation of flow control. This is not a problem, since the violation of flow control in this case is bounded.

In multithreaded drivers, the q argument may not reference q_next (for example, an argument of q->q_next is erroneous in a multithreaded driver and is disallowed by the DDI/DKI). bcanputnext(q) is provided as a multiprocessor-safe equivalent to the common call bcanput(q->q_next), which is no longer allowed [see canputnext(D3)].

If pri is 0, the bcanput call is equivalent to a call to canput.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

bcanputnext - test for flow control in a specified priority band

#include <sys/types.h>
#include <sys/stream.h>

int bcanputnext(queue_t *q, uchar_t pri);

bcanputnext searches through the stream (starting at q->q_next ) until it finds a queue containing a service routine, or until it reaches the end of the stream. If found, the queue containing the service routine is tested to see if a message in priority band pri can be enqueued. If the band is full, bcanputnext marks the queue to automatically back-enable the caller's service routine when the amount of data in messages on the queue has reached its low water mark.

Arguments:

q

Pointer to a message queue.

pri

Message priority.

Return Values:

bcanputnext returns 1 if a message of priority pri can be sent in the stream, or 0 if the priority band is flow-controlled. If bcanputnext reaches the end of the stream without finding a queue with a service routine, then it returns 1.
 

Usage:

The driver writer is responsible for both testing a queue with bcanputnext and refraining from placing a message on the queue if bcanputnext fails.

It is possible because of race conditions to test for room using bcanputnext and get an indication that there is room for a message, and then have the queue fill up before subsequently enqueuing the message, causing a violation of flow control. This is not a problem since the violation of flow control in this case is bounded.

In multithreaded drivers, the q argument to bcanput(D3) and bcanputnext may not reference q_next (for example, an argument of q->q_next is erroneous in a multithreaded driver and is disallowed by the DDI/DKI). bcanputnext(q) is provided as a multiprocessor-safe equivalent to the common all bcanput (q->q_next), which is no longer allowed.

If pri is 0, the bcanputnext call is equivalent to a call to canputnext.
 

Level:

Initialization, Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

bufcall - call a function when a buffer becomes available

 

#include <sys/types.h>
#include <sys/stream.h>

toid_t bufcall(uint_t size, int pri, void (*func)(), long long arg);

When a buffer allocation request fails, the function bufcall can be used to schedule the routine func, to be called with the argument arg, when a buffer of at least size bytes becomes available. bufcall serves, in effect, as a timeout call of indeterminate length.

Arguments:

 

size

Number of bytes in the buffer to be allocated (from the failed allocb(D3) request).

pri

Priority of the allocb allocation request (BPRI_LO, BPRI_MED, or BPRI_HI).

func

Function or drive routine to be called when a buffer becomes available.

arg

Argument to the function to be called when a buffer becomes available.

 

Return Values:

Upon success, bufcall returns a non-zero value that identifies the scheduling request. On failure, bufcall returns 0.
 

Usage:

When func runs, all interrupts from STREAMS devices will be blocked. On multiprocesssor systems, when func runs, all interrupts from STREAMS devices will be blocked on the processor on which func is running. func will have no user context and may not call any func that sleeps.

Even when func is called, allocb can still fail if another module or driver had allocated the buffer before func was able to call allocb.

The pri argument is the priority of the allocation request.

The nonzero identifier returned by bufcall may be passed to unbufcall(D3) to cancel the request.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function.

NAME

canput - test for room in a message queue

#include <sys/stream.h>

int canput(queue_t *q);

DESCRIPTION

canput tests if there is room for a message in the queue pointed to by q. The queue must have a service procedure.

Arguments:

q

Pointer to the message queue.

 

Return Values:

canput returns 1 if a message can be placed on the queue. 0 is returned if a message cannot be enqueued because of flow control.
 
 

Usage:

The driver is responsible for both testing a queue with canput and refraining from placing a message on the queue if canput fails.

It is possible because of race conditions to test for room using canput and get an indication that there is room for a message, and then have the queue fill up before subsequently enqueuing the message, causing a violation of flow control. This is not a problem, since the violation of flow control in this case is bounded.

In multithreaded drivers, the q argument may not reference q_next (for example, an argument of q->q_next is erroneous in a multithreaded driver and is disallowed by the DDI/DKI). canputnext(q) is provided as a multiprocessor-safe equivalent to the common call canput(q->q_next), which is no longer allowed [see canputnext(D3)].
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

canputnext - test for flow control in a stream

#include <sys/stream.h>

int canputnext(queue_t *q);

canputnext searches through the stream (starting at q->q_next) until it finds a queue containing a service routine, or until it reaches the end of the stream. If found, the queue containing the service routine is tested to see if there is room for a message in the queue. If the queue is full, canputnext marks the queue to automatically back-enable the caller's service routine when the amount of data in messages on the queue has reached its low water mark.

Arguments:

q

Pointer to a message queue.

 

Return Values:

canputnext returns 1 if a message can be sent in the stream, or 0 if the stream is flow-controlled. If canputnext reaches the end of the stream without finding a queue with a service routine, then it returns 1.
 

Usage:

The driver is responsible for both testing a queue with canputnext and refraining from placing a message on the queue if canputnext fails.

It is possible because of race conditions to test for room using canputnext and get an indication that there is room for a message, and then have the queue fill up before subsequently enqueuing the message, causing a violation of flow control. This is not a problem since the violation of flow control in this case is bounded.

The q argument may not reference q_next (for example, an argument of q->q_next is erroneous in a multithreaded driver and is disallowed by the DDI/DKI).

In multithreaded drivers, the q argument may not reference q_next (for example, an argument of q->q_next is erroneous in a multithreaded driver and is disallowed by the DDI/DKI). canputnext(q) is provided as a multiprocessor-safe equivalent to the common call canput (q->q_next), which is no longer allowed.

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

copyb - copy a message block

#include <sys/stream.h>

mblk_t *copyb(mblk_t *bp);

copyb allocates a new message block, and copies into it the data from the block pointed to by bp. The new block will be at least as large as the block being copied. The b_rptr and b_wptr members of the message block pointed to by bp are used to determine how many bytes to copy.

Arguments:

bp

Pointer to the message block from which data are copied.

 

Return Values:

On success, copyb returns a pointer to the newly allocated message block containing the copied data. On failure, it returns a NULL pointer.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function. In module, driver-defined locks must not be held.

NAME

copymsg - copy a message

#include <sys/stream.h>

mblk_t *copymsg(mblk_t *mp);

copymsg forms a new message by allocating new message blocks, copies the contents of the message referred to by mp (using the copyb(D3) function), and returns a pointer to the new message.

Arguments:

mp

Pointer to the message to be copied.

 

Return Values:

On success, copymsg returns a pointer to the new message. On failure, it returns a NULL pointer.
 
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function. In module, driver-defined locks must not be held.

NAME

datamsg - test whether a message is a data message

#include <sys/types.h>
#include <sys/stream.h>

int datamsg(uchar_t type);

The datamsg function tests the type of message to determine if it is a data message type (M_DATA, M_DELAY, M_PROTO, or M_PCPROTO).

Arguments:

 

type

The type of message to be tested.

 

Return Values:

datamsg returns 1 if the message is a data message and 0 if the message is any other type.
 
 

Usage:

The db_type field of the datab structure contains the message type. This field may be accessed through the message block using mp->b_datap->db_type.
 
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

The put(D2) routine enqueues all data messages for handling by the srv(D2) (service) routine. All nondata messages are handled in the put routine.

           xxxput(q, mp)
           queue_t *q;
           mblk_t *mp;
             {
                if (datamsg(mp->b_datap->db_type)) {
                putq(q, mp);
                return;
                }
                switch (mp->b_datap->db_type) {
                case M_FLUSH:
           ...
                }
          }

NAME

dupb - duplicate a message block

#include <sys/stream.h>

mblk_t *dupb(mblk_t *bp);

dupb creates a new message block structure that references the same data block that is referenced by bp. Unlike copyb(D3), dupb does not copy the information in the data block, but creates a new structure to point to it.

Arguments:

bp

Pointer to the message block to be duplicated.

 

Return Values:

On success, dupb returns a pointer to the new message block. On failure, it returns a NULL pointer.
 

Usage:

The following figure shows how the db_ref field of the data block structure has been changed from 1 to 2, reflecting the increase in the number of references to the data block. The new message block contains the same information as the first. Note that b_rptr and b_wptr are copied from bp, and that db_ref is incremented.


 

Level:

Base or Interrupt.

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

NAME

dupmsg - duplicate a message

#include <sys/stream.h>

mblk_t *dupmsg(mblk_t *mp);

dupmsg forms a new message by duplicating the message blocks in the message pointed to by mp and linking them via their b_cont pointers.

Arguments:

mp

Pointer to the message.

 

Return Values:

On success, dupmsg returns a pointer to the new message. On failure, it returns a NULL pointer.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

NAME

enableok - allow a queue to be serviced

#include <sys/stream.h>

void enableok(queue_t *q);

The enableok function allows the service routine of the queue pointed to by q to be rescheduled for service. It cancels the effect of a previous use of the noenable(D3) function on q.

Arguments:

q

Pointer to the queue.

 

Return Values:

None
 
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

The qrestart routine uses two STREAMS functions to reenable a queue that has been disabled. The enableok function removes the restriction that prevented the queue from being scheduled when a message was enqueued. Then, if there are messages on the queue, it is scheduled by calling qenable(D3).

           void
            qrestart(q)
                queue_t *q;
           {
                enableok(q);
                if (q->q_first)
                     qenable(q);
           }

 

NAME

esballoc - allocate a message block using an externally-supplied buffer

#include <sys/types.h>
#include <sys/stream.h>

mblk_t *esballoc(uchar_t *base, int size, int pri, frtn_t *fr_rtnp);

esballoc creates a STREAMS message and attaches a driver-supplied data buffer in place of a STREAMS data buffer. It allocates a message and data block header only. The driver-supplied data buffer, pointed to by base, is used as the data buffer for the message.
When freeb(D3) is called to free the message, on the last reference to the message, the driver's free-routine, specified by the free_func field in the free_rtn(D4) structure, is called with one argument, specified by the free_arg field, to free the data buffer.

Arguments:

 

base	Address of driver-supplied data buffer.
size	Number of bytes in data buffer.
pri	Priority of allocation request (used to allocate the message and data blocks). The effective values are BPRI_LO, BPRI_MED, and BPRI_HI.
fr_rtnp	Pointer to the free-routine data structure.

 
 

Return Values:

On success, a pointer to the newly allocated message block is returned. On failure, NULL is returned.
 

Usage:

Instead of requiring a specific number of arguments, the free_arg field is defined of type char *.This way, the driver can pass a pointer to a structure if more than one argument is needed.

When the free_func function runs, interrupts from all STREAMS devices will be blocked. It has no user context and may not call any routine that sleeps. The function may not access any dynamically allocated data structures that might no longer exist when it runs.
 

Level:

Base or Interrupt.
 
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

NAME

esbbcall - call a function when an externally-supplied buffer can be allocated

#include <sys/types.h>
#include <sys/stream.h>

int esbbcall(int pri, void (*func)(), long long arg);

If esballoc(D3) is unable to allocate a message block header and a data block header to go with its externally supplied data buffer, the function esbbcall can be used to schedule the routine func, to be called with the argument arg when memory becomes available. esbbcall, like bufcall(D3), serves, in effect, as a timeout call of indeterminate length.

Arguments:

 

pri	Priority of the esballoc(D3) allocation request.
func	Function to be called when a buffer becomes available.
arg	Argument to the function to be called when a buffer becomes available.

 
 

Return Values:

On success, esbbcall returns a nonzero value that identifies the scheduling request. On failure, esbbcall returns 0.
 

Usage:

When func runs, all interrupts from STREAMS devices will be blocked. On multiprocessor systems, the interrupts will be blocked only on the processor on which func is running. func will have no user context and may not call any function that sleeps.

Even when func is called, esballoc can still fail if another module or driver had allocated the memory before func was able to call allocb.

The nonzero identifier returned by esballoc may be passed to unbufcall(D3) to cancel the request.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

NAME

flushband - flush messages in a specified priority band

#include <sys/types.h>
#include <sys/stream.h>

void flushband(queue_t *q, uchar_t pri, int flag);

The flushband function flushes messages associated with the priority band specified by pri. If pri is 0, only normal and high priority messages are flushed. Otherwise, messages are flushed from the band pri according to the value of flag.

If the band's count falls below the low water mark and someone wants to write to the band, the nearest upstream or downstream service procedure is enabled.

Arguments:

q

Pointer to the queue.

pri

 Priority band of messages to be flushed.

flag

Determines messages to flush.

 

Return Values:

None
 

Usage:

Valid values for flag are:

FLUSHDATA	Flush only data messages (types M_DATA, M_DELAY, M_PROTO, and M_PCPROTO).
FLUSHALL	Flush all messages.

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

flushq - flush messages on a queue

#include <sys/stream.h>

void flushq(queue_t *q, int flag);

flushq frees messages on a queue by calling freemsg(D3) for each message. If the queue's count falls below the low water mark and someone wants to write to the queue, the nearest upstream or downstream service procedure is enabled.

Arguments:

q

Pointer to the queue to be flushed.

flag

Determines messages to flush

 

Return Values:

None
 

Usage:

Valid values for flag are:

 

FLUSHDATA	Flush only data messages (types M_DATA, M_DELAY, M_PROTO, and M_PCPROTO).
FLUSHALL	Flush all messages.

 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

freeb - free a message block

#include <sys/stream.h>

void freeb(mblk_t *bp);

freeb deallocates a message block. If the reference count of the db_ref member of the datab(D4) structure is greater than 1, freeb decrements the count and returns. Otherwise, if db_ref equals 1, it deallocates the message block and the corresponding data block and buffer.

If the data buffer to be freed was allocated with esballoc(D3), the driver is notified that the attached data buffer needs to be freed by calling the free-routine [see free_rtn(D4)] associated with the data buffer. Once this is accomplished, freeb releases the STREAMS resources associated with the buffer.
 

Arguments:

bp

 Pointer to the message block to be allocated.

 

Return Values:

None
 
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

NAME

freemsg - free a message

#include <sys/stream.h>

void freemsg(mblk_t *mp);

freemsg frees all message blocks, data blocks, and data buffers associated with the message pointed to by mp. freemsg walks down the b_cont list [see msgb(D4)], calling freeb(D3) for every message block in the message.

Arguments:

mp

Pointer to the message to be deallocated.

 

Return Values:

None
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

NAME

freezestr - freeze the state of a stream

#include <sys/types.h>
#include <sys/stream.h>

int freezestr(queue_t *q);

freezestr freezes the state of the stream containing the queue specified by q. Freezing the stream prevents any further entries into open, close, put, and service procedures on the stream and prevents any messages from being placed on or taken off any queues in the stream (except by the caller of freezestr).

Freezing the stream does not automatically stop all functions that are running within the stream; functions will continue to run until they attempt to perform some operation which changes the state of the stream, at which point they will be forced to wait for the stream to be unfrozen by a call to unfreezestr(D3).

Arguments:

q

Pointer to a message queue.

 

Return Values:

freezestr returns the ID previous interrupt priority level which is typically used in a subsequent call to unfreezestr.
 

Usage:

Drivers and modules must freeze the stream while they manipulate its queues directly. This includes searching the queues and for the duration of any calls to insq(D3), rmvq(D3), strqset(D3), and strqget(D3).
 

Level:

Base or Interrupt.

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function. In module, driver-defined locks must not be held.

NAME

getq - get the next message from a queue

#include <sys/stream.h>

mblk_t *getq(queue_t *q);

getq gets the next available message from the top of the queue pointed to by q. It handles flow control, restarting I/O that was blocked as needed.

Arguments:

q

Pointer to the queue from which the message is to be retrieved.

 

Return Values:

If there is a message to retrieve, getq returns a pointer to it. If no message is queued, getq returns a NULL pointer.
 

Usage:

getq is typically used by service routines [see srv(D2)] to retrieve queued messages.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

insq - insert a message into a queue

#include <sys/stream.h>

int insq(queue_t *q, mblk_t *emp, mblk_t *nmp);

insq inserts a message into a queue. The message to be inserted, nmp, is placed in the queue pointed to by q, immediately before the message, emp. If emp is NULL, the new message is placed at the end of the queue. All flow control parameters are updated. The service procedure is scheduled to run unless disabled by a previous call to noenable(D3).

Arguments:

q

Pointer to the queue containing message emp.

emp

Pointer to the existing message before which the new message is to be inserted.

nmp

 Pointer to the new message to be inserted.

 

Return Values:

If nmp was successfully enqueued, insq returns 1. Otherwise, insq returns 0.
 

Usage:

Messages are ordered in the queue based on their priority, as described int srv(D2). If an attempt is made to insert a message out of order in the queue, then nmp is not enqueued.

The insertion can fail if there is not enough memory to allocate the accounting data structures used with messages whose priority bands are greater than zero.

If emp is non-NULL, it must point to a message in the queue pointed to by q, or a system panic could result.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller must have the stream frozen [see freezestr(D3)] when calling this function.

NAME

linkb - concatenate two message blocks

#include <sys/stream.h>
void linkb(mblk_t *mp1, mblk_t *mp2);

linkb appends the message mp2 to the tail of message mp1. The continuation pointer (b_cont) of the last message block in the first message is set to point to the second message.



Arguments:

mp1

Pointer to the message to which mp2 is to be added.

mp2

Pointer to the message to be added.

 

Return Values:

None.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

NAME

msgdsize - return number of bytes of data in a message

#include <sys/stream.h>

int msgdsize(mblk_t *mp);

msgdsize counts the number of bytes of data in the message pointed to by mp. Only bytes included in message blocks of type M_DATA are included in the count.

Arguments:

mp

Pointer to the message to be evaluated.

 

Return Values:

The number of bytes of data in the message.
 
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

NAME

msgpullup - concatenate bytes in a message

#include <sys/stream.h>

mblk_t *msgpullup(mblk_t *mp, int len);

msgpullup concatenates and aligns the first len data bytes of the message pointed to by mp, copying the data into a new message. All message blocks that remain in the original message once len bytes have been concatenated and aligned (including any partial message blocks) are copied and linked to the end of the new message, so that the length of the new message is equal to the length of the original message.

The original message is unaltered. If len equals _1, all data are concatenated. If len bytes of the same message type cannot be found, msgpullup fails and returns NULL.

Arguments:

mp

 Pointer to the message whose blocks are to be concatenated.

len

Number of bytes to concatenate.

 

Return Values:

Upon success, msgpullup returns a pointer to the new message. On failure, msgpullup returns NULL.
 
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

NAME

noenable - prevent a queue from being scheduled

#include <sys/stream.h>

void noenable(queue_t *q);

The noenable function prevents the service routine of the queue pointed to by q from being scheduled for service by insq(D3), putbq(D3), or putq(D3), when enqueuing a message that is not a high priority message.

Arguments:

q

Pointer to the queue.

 

Return Values:

None
 

Usage:

The high-priority-only message restriction can be lifted with the enableok(D3) function. noenable does not prevent the queue's service routine from being scheduled when a high priority message is enqueued, or by an explicit call to qenable(D3).
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

OTHERQ - get a pointer to queue's partner queue

#include <sys/stream.h>

queue_t *OTHERQ(queue_t *q);

The OTHERQ function returns a pointer to the other of the two queue structures that make up an instance of a STREAMS module or driver.

Arguments:

q

Pointer to the queue.

 

Return Values:

OTHERQ returns a pointer to a queue's partner.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Multithreaded drivers may hold driver-defined mask locks, and simple locks across calls to this function.

Examples

 

This routine sets the minimum packet size, the maximum packet size, the high water mark, and the low water mark for the read and write queues of a given module or driver. It is passed either one of the queues. This could be used if a module or driver wished to update its queue parameters dynamically.

          void
           set_q_params(queue_t *q, long min, long max, ulong_t hi, ulong_t lo)
           {
                int pl;     /* for multithreaded drivers */
                pl = freezestr(q); /* for multithreaded drivers */
                (void) strqset(q, QMINPSZ, 0, min);
                (void) strqset(q, QMAXPSZ, 0, max);
                (void) strqset(q, QHIWAT, 0, hi);
                (void) strqset(q, QLOWAT, 0, lo);
                (void) strqset(OTHERQ(q), QMINPSZ, 0, min);
                (void) strqset(OTHERQ(q), QMAXPSZ, 0, max);
                (void) strqset(OTHERQ(q), QHIWAT, 0, hi);
                (void) strqset(OTHERQ(q), QLOWAT, 0, lo);
                unfreezestr(q,pl); /* for multithreaded drivers */
          }

 

NAME

pullupmsg - concatenate bytes in a message

#include <sys/stream.h>

int pullupmsg(mblk_t *mp, int len);

pullupmsg concatenates and aligns the first len data bytes of the message pointed to by mp, combining multiple message blocks into a single block. If len equals _1, all data are concatenated. If len bytes of the same message type cannot be found, pullupmsg fails and returns 0.

Arguments:

mp

Pointer to the message whose blocks are to be concatenated.

len

Number of bytes to concatenate.

 

Return Values:

On success, pullupmsg returns 1. On failure, pullupmsg returns 0.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep.

NAME

put - call a put procedure

#include <sys/stream.h>

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

put calls the put procedure (put(D2) entry point) for the queue specified by q, passing it the arguments q and mp.

Arguments:

q

Pointer to a message queue.

mp

Pointer to the message block being passed.

 

Return Values:

None
 

Usage:

put is typically used by a driver or module to call its own put procedure so that the proper accounting is done in the stream.

On multiprocessor systems, DDI/DKI conforming drivers and modules are no longer permitted to call put procedures directly, but must call through the appropriate STREAMS utility function. For example, put(D3), putnext(D3), putctl(D3), putnextctl(D3), qreply(D3). put(q, mp) is provided as a DDI/DKI-conforming equivalent to a direct call to a put procedure, which is no longer allowed.

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined locks may not be held across calls to this function.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

putbq - place a message at the head of a queue

#include <sys/stream.h>

int putbq(queue_t *q, mblk_t *bp);

putbq puts a message back at the head of a queue. If messages of a higher priority are on the queue, then bp is placed at the head of its corresponding priority band. See srv(D2) for more information about message priorities.

All flow control parameters are updated. The queue's service routine is scheduled if it has not been disabled by a previous call to noenable(D3).

Arguments:

q

Pointer to the queue.

bp

Pointer to the message.

 

Return Values:

putbq returns 1 on success and 0 on failure.
 

Usage:

putbq is usually called when bcanput(D3) or canput(D3) [or, for multithreaded drivers, bcanputnext(D3) or canputnext(D3)] determines that the message cannot be passed on to the next stream component.

putbq can fail if there is not enough memory to allocate the accounting data structures used with messages whose priority bands are greater than zero.

High priority messages should never be put back on a queue from within a service routine.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

putctl - send a control message to a queue

#include <sys/stream.h>

int putctl(queue_t *q, int type);

putctl tests the type argument to make sure a data type has not been specified, and then attempts to allocate a message block. putctl fails if type is M_DATA, M_PROTO, or M_PCPROTO, or if a message block cannot be allocated. If successful, putctl calls the put(D2) routine of the queue pointed to by q, passing it the allocated message.

Arguments:

q

Pointer to the queue to which the message is to be sent.

type

 Message type (must be a control type).

 

Return Values:

On success, 1 is returned. Otherwise, if type is a data type, or if a message block cannot be allocated, 0 is returned.
 
 

Usage:

In multithreaded drivers, the q argument may not reference q_next (for example, an argument of q->q_next is erroneous in a multithreaded driver and is disallowed by the DDI/DKI). putnextctl(q, type) is provided as a multiprocessor-safe equivalent to the common call putctl(q->q_next, type), which is no longer allowed.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined basic locks, read/write locks, and sleep locks may not be held across calls to this function.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function..

NAME

putctl1 - send a control message with a one-byte parameter to a queue

#include <sys/stream.h>

int putctl1(queue_t *q, int type, int param);

putctl1, like putctl(D3), tests the type argument to make sure a data type has not been specified, and attempts to allocate a message block. The param parameter can be used, for example, to specify the signal number when an M_PCSIG message is being sent. putctl1 fails if type is M_DATA, M_PROTO, or M_PCPROTO, or if a message block cannot be allocated. If successful, putctl1 calls the put(D2) routine of the queue pointed to by q, passing it the allocated message.

Arguments:

 

q	Pointer to the queue to which the message is to be sent.
type	Message type (must be a control type).
param	One-byte parameter.

 
 

Return Values:

Upon success, 1 is returned. Otherwise, if type is a data type, or if a message block cannot be allocated, 0 is returned.
 

Usage:

In multithreaded drivers, the q argument to putctl1 and putnextctl1(D3) may not reference q_next (for example, an argument of q->q_next is erroneous in a multithreaded driver and is disallowed by the DDI/DKI). putnextctl1(q, type) is provided as a multiprocessor-safe equivalent to the common call putctl1(q->q_next, type), which is no longer allowed.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined locks may not be held across calls to this function.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

putnext - send a message to the next queue

#include <sys/stream.h>

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

DESCRIPTION

The putnext function is used to pass a message to the put(D2) routine of the next queue ( q->q_next ) in the stream.

Arguments:

q

Pointer to the queue from which the message mp will be sent.

mp

Pointer to the message to be passed.

 

Return Values:

Ignored
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined locks may not be held across calls to this function.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

putnextctl - send a control message to a queue

#include <sys/stream.h>

int putnextctl(queue_t *q, int type);

putnextctl tests the type argument to make sure a data type has not been specified, and then attempts to allocate a message block. putnextctl fails if type is M_DATA, M_PROTO, or M_PCPROTO, or if a message block cannot be allocated. If successful, putnextctl calls the put(D2) procedure of the queue pointed to by q->q_next, passing it the allocated message.

Arguments:

q

Pointer to the queue from which the message is to be sent.

type

Message type (must be a control type).

 

Return Values:

Upon successful completion, putnextctl returns 1. If type is a data type, or if a message block cannot be allocated, 0 is returned.
 

Usage:

In multithreaded drivers, the q argument to putctl(D3) and putnextctl may not reference q_next (for example, an argument of q->q_next is erroneous in a multithreaded driver and is disallowed by the DDI/DKI). putnextctl(q, type) is provided as a multiprocessor-safe equivalent to the common call putctl(q->q_next, type), which is no longer allowed.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined locks may not be held across calls to this function.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

putnextctl1 - send a control message with a one-byte parameter to a queue

#include <sys/stream.h>

int putnextctl1(queue_t *q, int type, int param);

putnextctl1 tests the type argument to make sure a data type has not been specified, and then attempts to allocate a message block. putnextctl1 fails if type is M_DATA, M_PROTO, or M_PCPROTO, or if a message block cannot be allocated. If successful, putnextctl calls the put(D2) procedure of the queue pointed to by q->q_next, passing it the allocated message with the one byte parameter specified by param.

Arguments:

 

q	Pointer to the queue from which the message is to be sent.
type	Message type (must be a control type).
param	One byte parameter

 
 

Return Values:

Upon successful completion, putnextctl1 returns 1. If type is a data type, or if a message block cannot be allocated, 0 is returned.
 

Usage:

In multithreaded drivers, the q argument to putctl1(D3) and putnextctl1 may not reference q_next (for example, an argument of q->q_next is erroneous in a multithreaded driver and is disallowed by the DDI/DKI). putnextctl1(q, type) is provided as a multiprocessor-safe equivalent to the common call putctl1(q->q_next, type), which is no longer allowed.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined locks may not be held across calls to this function.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

putq - put a message on a queue

#include <sys/stream.h>

int putq(queue_t *q, mblk_t *bp);

putq is used to put messages on a queue after the put(D2) routine has finished processing the message. The message is placed after any other messages of the same priority, and flow control parameters are updated. The queue's service routine is scheduled if it has not been disabled by a previous call to noenable(D3), or if the message being enqueued has greater than normal priority (that is, it is not in band zero).

Arguments:

q

Pointer to the queue.

bp

Pointer to the message.

 

Return Values:

putq returns 1 on success and 0 on failure.
 

Usage:

putq can fail if there is not enough memory to allocate the accounting data structures used with messages whose priority bands are greater than zero.

Level:

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

qenable - schedule a queue's service routine to be run

#include <sys/stream.h>

void qenable(queue_t *q);

qenable puts the queue pointed to by q on the linked list of those whose service routines are ready to be called by the STREAMS scheduler.

Arguments:

q

Pointer to the queue.

 

Return Values:

None
 

Usage:

qenable works regardless of whether the service routine has been disabled by a prior call to noenable(D3).
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

qprocsoff - disable put and service routines

#include <sys/stream.h>

void qprocsoff(queue_t *rq);

qprocsoff disables the put and service routines of the driver or module whose read queue is pointed to by rq. It removes the queue's service routines from the list of service routines to be run and waits until any concurrent put or service routines are finished. When the routines are disabled in a module, messages flow around the module as if it were not present in the stream.

Arguments:

rq

Pointer to a read queue.

 

Return Values:

None
 

Usage:

qprocsoff must be called by the close(D2) routine of a driver or module before deallocating any resources on which the driver/module's put and service routines depend. Drivers or modules should call qprocsoff exactly once to disable put and service procedures. One additional effect of calling qprocsoff is that both the read and write queues are flushed.
 

Level:

Base only.
 

Synchronization Constraints:

Can sleep. Driver-defined locks may not be held across calls to this function.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

qprocson - enable put and service routines

#include <sys/stream.h>

void qprocson(queue_t *rq);

qprocson enables the put and service routines of the driver or module whose read queue is pointed to by rq. Prior to the call to qprocson, the put and service routines of a newly pushed module or newly opened driver are disabled. When the routines are disabled in a module, messages flow around the module as if it were not present in the stream.

Arguments:

rq

Pointer to a read queue.

 

Return Values:

None
 

Usage:

qprocson must be called by the first open of a module or driver after allocation and initialization of any resources on which the put and service routines depend. Modules or drivers should call qprocson exactly once to enable put and service procedures. qprocsoff is called (also exactly once) to disable these put and service procedures.
 

Level:

Base only.
 

Synchronization Constraints:

Can sleep. Driver-defined locks may not be held across calls to this function.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

qreply - send a message in the opposite direction in a stream

#include <sys/stream.h>

void qreply(queue_t *q, mblk_t *bp);

qreply sends a message in the opposite direction from that which q is pointing. It calls the OTHERQ(D3) function to find q's partner, and passes the message by calling the put(D2) routine of the next queue in the stream after q's partner.

Arguments:

q

Pointer to the queue from which the message is being sent.

bp

Pointer to the message to be sent in the opposite direction.

 

Return Values:

None
 

Level

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined locks may not be held across calls to this function.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

qsize - find the number of messages on a queue

#include <sys/stream.h>

int qsize(queue_t *q);

qsize evaluates the queue pointed to by q and returns the number of messages it contains.

Arguments:

q

Pointer to the queue to be evaluated.

pri

Priority of the request.

 

Return Values:

If there are no messages on the queue, qsize returns 0. Otherwise, it returns the number of messages on the queue.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

RD - get a pointer to the read queue

#include <sys/stream.h>

queue_t *RD(queue_t *q);

The RD function accepts a queue pointer as an argument and returns a pointer to the read queue of the same module or driver.

Arguments:

q

Pointer to the queue whose read queue is to be returned.

 

Return Values:

The pointer to the read queue.
 

Usage:

Note that when RD is passed a read queue pointer as an argument, it returns a pointer to this read queue.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

NAME

rmvb - remove a message block from a message

#include <sys/stream.h>

mblk_t *rmvb(mblk_t *mp, mblk_t *bp);

rmvb removes the message block specified by bp from the message specified mp and returns a pointer to the altered message.

Arguments:

mp

Pointer to the message from which a message block is to be removed.

bp

Pointer to the message block to be removed.

 

Return Values:

On success, a pointer to the message (minus the removed block) is returned. If bp was the only block in the message before rmvb was called, NULL is returned. If the designated message block (bp) was not in the message, _1 is returned.
 

Usage:

The message block is not freed, merely removed from the message. It is the caller's responsibility to free the message block.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

NAME

rmvq - remove a message from a queue

#include <sys/stream.h>

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

rmvq removes the message specified by mp from the queue specified by q.

Arguments:

q

Pointer to the queue containing the message to be removed.

mp

 Pointer to the message to remove.

 

Return Values:

None
 

Usage:

A message can be removed from anywhere in a queue. To prevent modules and drivers from having to deal with the internals of message linkage on a queue, either rmvq or getq(D3) should be used to remove a message from a queue.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks, read/write locks, and sleep locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

SAMESTR - test if next queue is of the same type

#include <sys/stream.h>

int SAMESTR(queue_t *q);

The SAMESTR function checks whether the next queue in a stream (if it exists) is of the same type as the current queue (that is, both are read queues or both are write queues).

Arguments:

q

Pointer to the queue.

 

Return Values:

SAMESTR returns 1 if the next queue is of the same type as the current queue. It returns 0 if the next queue does not exist or if it is not of the same type.
 
 

Usage:

This function can be used to determine the point in a STREAMS-based pipe where a read queue is linked to a write queue.

In multithreaded drivers, the q argument may not reference q_next (for example, an argument of q->q_next is erroneous in a multithreaded driver and is disallowed by the DDI/DKI).
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function. In module, driver-defined locks must not be held.

The caller cannot have the stream frozen [see freezestr(D3)] when calling this function.

NAME

strqget - get information about a queue or band of the queue

#include <sys/types.h>
#include <sys/stream.h>

int strqget(queue_t *q, qfields_t what, uchar_t pri, long *valp);

strqget gives drivers and modules a way to get information about a queue or a particular priority band of a queue without directly accessing STREAMS data structures.

Arguments:

q

Pointer to the queue.

what

The field of the queue about which to return information.

pri

Priority band of the queue about which to obtain information.

valp

Pointer to the memory location where the value is to be stored.

 

Return Values:

Upon success, 0 is returned. An error number is returned on failure. The actual value of the requested field is returned through the reference parameter, valp.
 

Usage:

 

QHIWAT	High water mark of the specified priority band.
QLOWAT	Low water mark of the specified priority band.
QMAXPSZ	Maximum packet size of the specified priority band.
QMINPSZ	Minimum packet size of the specified priority band.
QCOUNT	Number of bytes of data in messages in the specified priority band.
QFIRST	Pointer to the first message in the specified priority band.
QLAST	Pointer to the last message in the specified priority band.
QFLAG	Flags for the specified priority band [see queue(D4)].

 
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

The caller must have the stream frozen [see freezestr(D3)] when calling this function.

NAME

strqset - change information about a queue or band of the queue

#include <sys/types.h> #include <sys/stream.h>

int strqset(queue_t *q, qfields_t what, uchar_t pri, long val);

strqset gives drivers and modules a way to change information about a queue or a particular priority band of a queue without directly accessing STREAMS data structures.

Arguments:

q

Pointer to the queue.

what

The field of the queue to change.

pri

Priority band of the queue to be changed.

val

New value for the field to be changed.

 

Return Values:

Upon success, 0 is returned. An error number is returned on failure.

Usage:

Valid what values are:

QHIWAT	High water mark of the specified priority band.
QLOWAT	Low water mark of the specified priority band.
QMAXPSZ	Maximum packet size of the specified priority band.
QMINPSZ	Minimum packet size of the specified priority band.

 
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

The caller must have the stream frozen [see freezestr(D3)] when calling this function.

NAME

unbufcall - cancel a pending bufcall request

 

#include <sys/stream.h>

void unbufcall(toid_t id);

unbufcall cancels the pending bufcall or esbbcall request specified by id.

Arguments:

id

Nonzero identifier returned from a prior call to bufcall(D3) or esbbcall(D3).

 

Return Values:

None.
 

Usage:

On uniprocessor systems, if unbufcall is called while any function called by the pending bufcall or esbbcall request is running, the call to unbufcall has no effect.

On multiprocessor systems, if unbufcall is called while any function called by the pending bufcall or esbbcall request is running, the call to unbufcall will not return until the function completes.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function.

NAME

unfreezestr - unfreeze the state of a stream

 #include <sys/types.h>
#include <sys/stream.h>

void unfreezestr(queue_t *q, int pl);

unfreezestr unfreezes the state of the stream containing the queue specified by q. Unfreezing the stream allows continuation of all activities that were forced to wait while the stream was frozen.

Arguments:

q

Pointer to a message queue.

pl

ID for unfreezing.

 

Return Values:

None.
 

Usage:

pl should be the value that was returned from the corresponding call to freezestr(D3).
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks may be held across calls to this function.

NAME

unlinkb - remove a message block from the head of a message

#include <sys/stream.h>

mblk_t *unlinkb( mblk_t *mp);

unlinkb removes the first message block from the message point to by mp.

Arguments:

mp

Pointer to the message.

 

Return Values:

unlinkb returns a pointer to the remainder of the message after the first message block has been removed. If there is only one message block in the message, NULL is returned.
 

Usage:

The removed message block is not freed. It is the caller's responsibility to free it.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.

NAME

WR - get a pointer to the write queue

#include <sys/stream.h>

queue_t *WR(queue_t *q);

The WR function accepts a queue pointer as an argument and returns a pointer to the write queue of the same module.

Arguments:

q

Pointer to the queue whose write queue is to be returned.

 

Return Values:

The pointer to the write queue.
 

Usage:

Note that when WR is passed a write queue pointer as an argument, it returns a pointer to this write queue.
 

Level:

Base or Interrupt.
 

Synchronization Constraints:

Does not sleep. Driver-defined mask locks and simple locks may be held across calls to this function.