[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Communications Technical Reference, Volume 1

DL_PROMISCON_REQ Primitive

Purpose

Requests that the data link service (DLS) provider enable promiscuous mode on a per stream basis, at either the physical level or the service access point (SAP) level.

Structure

The message consists of one M_PROTO message block, which contains the following structure:

typedef struct 
{
   ulong dl_primitive;
   ulong dl_level;
} dl_promiscon_req_t;

This structure is defined in /usr/include/sys/dlpi.h.

Description

A device in promiscuous mode lets a user view all packets, not just those destined for the user.

The DL_PROMISCON_REQ primitive requests that the DLS provider enable promiscuous mode on a per-stream basis, either at the physical level or at the SAP level.

The DLS provider routes all received messages on the media to the DLS user until either a DL_DETACH_REQ or a DL_PROMISCOFF_REQ primitive is received or the stream is closed.

If the DLS user enables the promiscuous mode at the physical level, the DLS user receives a copy of every packet on the wire for all SAPs.

If the DLS user enables the promiscuous mode at the SAP level, the DLS user receives a copy of every packet on the wire directed to that user for all SAPs.

If the DLS user enables the promiscuous mode for all multicast addresses, the DLS user receives all packets on the wire that have either a multicast or group destination address. This includes broadcast.

If the DLS user issues duplicate requests, the system returns a DL_OK_ACK primitive and does not perform the operation.

An application issuing the DL_PROMISCON_REQ primitive must have root authority. Otherwise, the DLS provider returns the DL_ERROR_ACK primitive with an error code of DL_ACCESS.

The DLS provider must not run in the interrupt environment. If it does, the system returns a DL_ERROR_ACK primitive with an error code of DL_SYSERR and an operating system error code of 0.

Parameters

dl_primitive Specifies the DL_PROMISCON_REQ primitive.
dl_level Indicates promiscuous mode at the physical or SAP level. Possible values include:
DL_PROMISC_PHYS Indicates promiscuous mode at the physical level.
DL_PROMISC_SAP Indicates promiscuous mode at the SAP level.
DL_PROMISC_MULTI Indicates promiscuous mode for all multicast addresses.

States

Valid The primitive is valid in any state in which an acknowledgement is not pending, with the exception of DL_UNATTACH.
New The resulting state is unchanged.

Acknowledgments

Successful The DL_OK_ACK primitive is sent to the DLS user.
Unsuccessful The DL_ERROR_ACK primitive is returned, and the resulting state is unchanged.

Error Codes

DL_ACCESS Indicates the DLS user does not have permission to issue the primitive.
DL_NOTSUPPORTED Indicates the primitive is known but not supported by the DLS provider.
DL_OUTSTATE Indicates the primitive was issued from an invalid state.
DL_SYSERR Indicates a system error occurred. The system error is indicated in the DL_ERROR_ACK primitive.
DL_UNSUPPORTED Indicates the DLS provider does not support the requested service on this stream.

Implementation Specifics

This primitive is part of Base Operating System (BOS) Runtime.

For binary compatibility purposes, a DL_UNITDATA_IND header is provided in the messages for promiscuous mode and raw mode. Be aware that this header will be removed in a future full release of AIX.

The following sample code fragment will work with the 4.1 version of dlpi and future releases of dlpi:

if (raw_mode) {
if (mp->b_datap->db_type == M_PROTO) {
union DL_primitives *p;
p = (union DL_primitives *)mp->b_rptr;
if (p->dl_primitive == DL_UNITDATA_IND) {
mblk_t *mpl = mp->b_cont;
freeb(mp);
mp = mpl;
}
}
}

The above code fragment simply discards the DL_UNITDATA_IND header.

For compatibility with future releases, it is recommended that you parse the frame yourself. The MAC and LLC headers are presented in the M_DATA message for promiscuous mode.

Related Information

The DL_OK_ACK primitive, DL_ERROR_ACK primitive, DL_DETACH_REQ primitive, DL_PROMISCOFF_REQ primitive.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]