Technical Reference: Communications, Volume 2

weldq Utility

Purpose

Establishes an uni-directional connection between STREAMS queues.

Syntax

#include <sys/stream.h>

int weldq ( q1, q2, q3, q4, func, arg, protect_q) queue_t *q1; queue_t *q2; queue_t *q3; queue_t *q4; weld_fcn_t func; weld_arg_t arg; queue_t *protect_q;

The weldq utility establishes an uni-directionnal connection (weld connection) between two STREAMS queues (q1 and q2). The weldq utility can be used to weld two pairs of queues in one call (q1 and q2, q3 and q4).

The welding operation is performed by changing the first queue's q_next pointer to point to the second queue. The weldq utility does not actually perform the operation. Instead, it creates a welding request which STREAMS performs asynchronously. STREAMS acquires the appropriate synchronization queues before performing the operation.

Callers that need to know when the welding operation has actually taken place should specify a callback function (func parameter) when calling the weldq utility. If the caller also specifies a synchronization queue (protect_q parameter), STREAMS acquires the synchronization associated with that queue when calling func. If the callback function is not a protected STREAMS utility, such as the qenable utility, the caller should always specify a protect_q parameter. The caller can also use this parameter to synchronize callbacks with protected STREAMS utilities.

Note: The stream.h header file must be the last included header file of each source file using the stream library.

Parameters

q1	Specifies the queue whose q_next pointer must be modified.
q2	Specifies the queue that will be welded to q1.
q3	Specifies the second queue whose q_next pointer must be modified. If the weldq utility is used to weld only one pair of queues, this parameter should be set to NULL.
q4	Specifies the queue that will be welded to q3.
func	Specifies an optional callback function that will execute when the welding operation has completed.
arg	Specifies the parameter for func.
protect_q	Specifies an optional synchronization queue that protects func.

Return Values

Upon successful completion, 0 (zero) is returned. Otherwise, an error code is returned.

Error Codes

The weldq utility fails if the following is true:

EAGAIN	The weld record could not be allocated. The caller may try again.
EINVAL	One or more parameters are not valid.
ENXIO	The weld mechanism is not installed.

Implementation Specifics

This utility is part of STREAMS Kernel Extensions.

Related Information

List of Streams Programming References in AIX 5L Version 5.1 Communications Programming Concepts.

STREAMS Overview in AIX 5L Version 5.1 Communications Programming Concepts.

Welding Mechanism in AIX 5L Version 5.1 Communications Programming Concepts.

The unweldq utility.