Technical Reference: Communications, Volume 1

DL_PROMISCOFF_REQ Primitive

Purpose

Requests that the data link service (DLS) provider disable 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_promiscoff_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_PROMISCOFF_REQ primitive requests that the DLS provider disable promiscuous mode on a per-stream basis, at either the physical level or the SAP level.

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

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

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

An application issuing the DL_PROMISCOFF_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_PROMISCOFF_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_NOTENAB	Indicates the mode is not enabled.
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 supply the requested level.

Implementation Specifics

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

Related Information

The DL_OK_ACK primitive, DL_ERROR_ACK primitive.