Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

OpenSolaris 2009.06 - man page for putpmsg (opensolaris section 2)

putmsg(2)				   System Calls 				putmsg(2)

NAME
       putmsg, putpmsg - send a message on a stream

SYNOPSIS
       #include <stropts.h>

       int putmsg(int fildes, const struct strbuf *ctlptr,
	    const struct strbuf *dataptr, int flags);

       int putpmsg(int fildes, const struct strbuf *ctlptr,
	    const struct strbuf *dataptr,int band, int flags);

DESCRIPTION
       The  putmsg() function creates a message  from user-specified buffer(s) and sends the mes-
       sage to a  STREAMS file. The message may contain either a data part, a  control	part,  or
       both.  The  data  and  control parts to be sent are distinguished by placement in separate
       buffers, as described below. The semantics of each part is defined by the  STREAMS  module
       that receives  the message.

       The  putpmsg() function does the same thing as putmsg(), but provides the user the ability
       to send messages in different priority bands. Except where noted, all information pertain-
       ing to putmsg() also pertains to putpmsg().

       The fildes argument specifies a file descriptor referencing an open stream. The ctlptr and
       dataptr arguments each point to a strbuf structure, which contains the following members:

	 int	  maxlen;     /* not used here */
	 int	  len;	      /* length of data */
	 void	  *buf;       /* ptr to buffer */

       The ctlptr argument points to the structure describing the control part,  if  any,  to  be
       included in the message. The buf member in the strbuf structure points to the buffer where
       the control information resides, and the len member indicates the number of  bytes  to  be
       sent. The maxlen member is not used in putmsg() (see getmsg(2)). In a similar manner, dat-
       aptr specifies the data, if any, to be included in  the message.  The flags argument indi-
       cates what type of message should be sent and is described later.

       To  send the data part of a message, dataptr must not be NULL, and  the len member of dat-
       aptr must have a value of 0 or greater. To send the control part of a message, the  corre-
       sponding  values must be set for  ctlptr. No data (control) part is sent if either dataptr
       (ctlptr) is  NULL or the len member of dataptr (ctlptr) is negative.

       For putmsg(), if a control part is specified, and flags is set to  RS_HIPRI, a high prior-
       ity  message  is  sent.	If  no	control  part is specified, and flags is set to RS_HIPRI,
       putmsg() fails and sets errno to EINVAL. If flags is set to  0,	a  normal  (non-priority)
       message is sent. If no control part and no data part are specified, and flags is set to 0,
       no message is sent, and 0 is returned.

       The stream head guarantees that the control part of a message generated by putmsg() is  at
       least 64 bytes in length.

       For  putpmsg(), the flags are different.  The flags argument is a bitmask with the follow-
       ing mutually-exclusive flags defined: MSG_HIPRI and  MSG_BAND.  If  flags  is  set  to  0,
       putpmsg()  fails and sets errno to EINVAL. If a control part is specified and flags is set
       to MSG_HIPRI and band is set to 0, a high-priority message is sent. If  flags  is  set  to
       MSG_HIPRI  and  either  no  control  part is specified or band is set to a non-zero value,
       putpmsg() fails and sets errno to EINVAL. If flags is set to MSG_BAND, then a  message  is
       sent in the priority band specified by band. If a control part and data part are not spec-
       ified and flags is set to MSG_BAND, no message is sent and 0 is returned.

       Normally, putmsg() will block if the stream write queue is full	due to internal flow con-
       trol  conditions.  For high-priority messages,  putmsg() does not block on this condition.
       For other messages,  putmsg() does not block when the write queue is full and  O_NDELAY or
       O_NONBLOCK is set. Instead, it fails and sets  errno to EAGAIN.

       The  putmsg()  or  putpmsg()  function  also  blocks, unless prevented by lack of internal
       resources, waiting  for the availability of message blocks in the  stream,  regardless  of
       priority   or  whether  O_NDELAY  or  O_NONBLOCK has been specified. No partial message is
       sent.

RETURN VALUES
       Upon successful completion, 0 is returned. Otherwise, -1 is returned and errno is  set  to
       indicate the error.

ERRORS
       The putmsg() and putpmsg() functions will fail if:

       EAGAIN	       A  non-priority	message was specified, the O_NDELAY or O_NONBLOCK flag is
		       set and the stream write queue is full due to internal flow control condi-
		       tions.

       EBADF	       The fildes argument is not a valid file descriptor open for writing.

       EFAULT	       The ctlptr or dataptr argument points to an illegal address.

       EINTR	       A signal was caught during the execution of the putmsg() function.

       EINVAL	       An undefined value was specified in flags; flags is set to RS_HIPRI and no
		       control part was supplied; or the stream referenced by  fildes  is  linked
		       below a multiplexor.

       ENOSR	       Buffers	could not be allocated for the message that was to be created due
		       to insufficient STREAMS memory resources.

       ENOSTR	       The fildes argument is not associated with a STREAM.

       ENXIO	       A hangup condition was generated downstream for the specified  stream,  or
		       the other end of the pipe is closed.

       EPIPE or EIO    The  fildes  argument  refers to a STREAMS-based pipe and the other end of
		       the pipe is closed.  A SIGPIPE signal is generated for the calling thread.
		       This  error  condition  occurs  only with SUS-conforming applications. See
		       standards(5).

       ERANGE	       The size of the data part of the message does not fall  within  the  range
		       specified  by  the  maximum and minimum packet sizes of the topmost stream
		       module. This value is also returned if the control part of the message  is
		       larger  than the maximum configured size of the control part of a message,
		       or if the data part of a message is larger  than  the  maximum  configured
		       size of the data part of a message.

       In  addition,  putmsg()	and putpmsg() will fail if the STREAM head had processed an asyn-
       chronous error before the call.	In this case, the value of errno  does	not  reflect  the
       result of putmsg() or putpmsg() but reflects the prior error.

       The putpmsg() function will fail if:

       EINVAL	 The flags argument is set to MSG_HIPRI and band is non-zero.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       Intro(2), getmsg(2), poll(2), read(2), write(2), attributes(5), standards(5)

       STREAMS Programming Guide

SunOS 5.11				    1 Nov 2003					putmsg(2)


All times are GMT -4. The time now is 06:36 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password