canput(D3) canput(D3)
NAME
canput - test for room in a message queue
SYNOPSIS
#include <sys/stream.h>
#include <sys/ddi.h>
int canput(queue_t *q);
Arguments
q Pointer to the message queue.
DESCRIPTION
canput 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 can be
enqueued. If the queue is full, canput 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.
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)].
Copyright 1994 Novell, Inc. Page 1
canput(D3) canput(D3)
Level
Base or Interrupt.
Synchronization Constraints
Does not sleep.
Driver-defined basic locks, read/write locks, and sleep locks
may be held across calls to this function.
The caller cannot have the stream frozen [see freezestr(D3)]
when calling this function.
Examples
See bufcall(D3) for an example of canput.
REFERENCES
bcanput(D3), bcanputnext(D3), canputnext(D3), putbq(D3),
putnext(D3)
NOTICES
Portability
All processors
Applicability
ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp
Copyright 1994 Novell, Inc. Page 2