'\" te
.\" Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
.TH sof_mblk_msghdr 9F "9 May 2012" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
sof_mblk_msghdr, sof_mblk_create \- access and create control messages
.SH SYNOPSIS
.LP
.nf
#include <sys/sockfilter.h>

boolean_t sof_mblk_msghdr(sof_handle_t \fIhdl\fR, mblk_t *\fImp\fR,
     struct msghdr *\fImsg\fR, int \fIflags\fR);
.fi

.LP
.nf
mblk_t *sof_mblk_create(sof_handle_t \fIhdl\fR, struct msghdr *\fImsg\fR,
     int \fIflags\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIhdl\fR\fR
.ad
.RS 9n
.rt  
per-socket filter handle
.RE

.sp
.ne 2
.mk
.na
\fB\fImsg\fR\fR
.ad
.RS 9n
.rt  
pointer to a message header structure, as defined in \fBsocket.h\fR(3HEAD)
.RE

.sp
.ne 2
.mk
.na
\fB\fImp\fR\fR
.ad
.RS 9n
.rt  
pointer to a \fBmsgb\fR(9S) structure
.RE

.sp
.ne 2
.mk
.na
\fB\fIflags\fR\fR
.ad
.RS 9n
.rt  
either 0 or \fBSOF_MBLK_CMSG\fR
.RE

.SH DESCRIPTION
.sp
.LP
The \fBsof_mblk_msghdr()\fR function is used to obtain message header information from a message block. On success, \fImsg_name\fR will point to a location within the message block containing address information, and \fImsg_namelen\fR will reflect the size of the address. Any changes made to the content pointed to by \fImsg_name\fR will be made to the underlying message block. The content pointed to by \fImsg_control\fR should be treated as opaque data unless \fBSOF_MBLK_CMSG\fR is specified. If \fBSOF_MBLK_CMSG\fR is specified, then the caller must also provide a buffer, pointed to by \fImsg_control\fR, where ancillary data will be stored. \fImsg_controllen\fR is updated on return to reflect the amount of ancillary data. If there is not enough room in the provided buffer to copy out all control data, then none of it will be copied, and \fBMSG_CTRUNC\fR will be set on \fImsg_flags\fR.
.sp
.LP
The \fBsof_mblk_create()\fR function tries to allocate a message block that is large enough to contain the address and control data provided in the message header, and copies the information into the newly created message block. If \fBSOF_MBLK_CMSG\fR is not specified, then \fImsg_control\fR should either be \fINULL\fR, or point to the opaque data returned in \fImsg_control\fR by a previous call to \fBsof_mblk_msghdr()\fR. If \fBSOF_MBLK_CMSG\fR is specified, then \fImsg_control\fR points to a buffer containing \fBcmsghdr\fR structures.
.SH RETURN VALUES
.sp
.LP
The \fBsof_mblk_msghdr()\fR function returns \fBB_TRUE\fR if a message header was found, and \fBB_FALSE\fR otherwise.
.sp
.LP
If successful, \fBsof_mblk_create()\fR returns a pointer to the allocated message block. On failure, \fBsof_mblk_create()\fR returns a null pointer.
.SH EXAMPLES
.LP
\fBExample 1 \fRAccess and modify address information
.sp
.in +2
.nf
mblk_t *xx_data_in(sof_handle_t hdl, void *cookie, mblk_t *mp)
{
     xxpriv_t *priv = cookie;
     struct msghdr msg;

     /*
      * Extract name information.  The filter is not interested in
      * control data.
      */
     if (sof_mblk_msghdr(hdl, mp, &msg, 0)) {
         (void) strncpy(msg.msg_name, priv->xx_addr,
             msg.msg_namelen);
     }

     return (mp);
}
.fi
.in -2

.LP
\fBExample 2 \fRUpdate ancillary data
.sp
.in +2
.nf
mblk_t *xx_data_in(sof_handle_t hdl, void *cookie, mblk_t *mp)
{
     xxpriv_t *priv = cookie;
     struct msghdr msg;
     char buf[XX_BUFLEN];

     msg.msg_control = buf;
     msg.msg_controllen = sizeof (buf);

     /* Process any ancillary data. */
     if (sof_mblk_msghdr(hdl, mp, &msg, SOF_MBLK_CMSG)) {
         mblk_t *nmp;

         xx_proc_ctrl(&msg);

         /* msghdr has cmsghdr control data. */
         nmp = sof_mblk_create(hdl, &msg, SOF_MBLK_CMSG);
         if (nmp != NULL) {
             nmp->b_cont = mp->b_cont;
             freeb(mp);
             mp = nmp;

         }
     }

     return (mp);
}
.fi
.in -2

.SH CONTEXT
.sp
.LP
The \fBsof_mblk_msghdr()\fR and \fBsof_mblk_create()\fR functions can be called from any context.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Availabilitysystem/kernel
_
Interface StabilityUncommitted
.TE

.SH SEE ALSO
.sp
.LP
\fBsocket.h\fR(3HEAD), \fBattributes\fR(5), \fBsofop_data_in\fR(9E), \fBsof_inject_data_in\fR(9F), \fBmsgb\fR(9S)