Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  str-
       buf *dataptr, int band, int flags);

DESCRIPTION
       The  putmsg() function creates a	message	 from user-specified buffer(s)
       and sends the message to	a  STREAMS file. The message may  contain  ei-
       ther  a	data part, a control part, or both. The	data and control parts
       to be sent are distinguished by placement in separate  buffers, as  de-
       scribed	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. Ex-
       cept where noted, all information pertaining 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	struc-
       ture, 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 str-
       buf  structure  points  to the buffer where the control information re-
       sides, 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, dataptr specifies the data, if any, to be included in  the mes-
       sage.  The flags	argument indicates 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	dataptr	must have a value of 0 or greater. To send the
       control part of a message, the corresponding 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	priority message is sent. If no	control	part is	speci-
       fied, 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  bit-
       mask with the following mutually-exclusive flags	defined: MSG_HIPRI and
       MSG_BAND. If flags is set to 0, putpmsg() fails and sets	errno to  EIN-
       VAL.  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	specified 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 control 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 conditions.

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

       EFAULT	       The ctlptr or dataptr argument points to	an illegal ad-
		       dress.

       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	multi-
		       plexor.

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

       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	condi-
		       tion 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  asynchronous  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),	 stan-
       dards(5)

       STREAMS Programming Guide

SunOS 5.10			  1 Nov	2003			     putmsg(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=putmsg&sektion=2&manpath=SunOS+5.10>

home | help