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 writ-
	     ing.

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

       EINTR A signal was caught during	the execution of  the  putmsg()	 func-
	     tion.

       EINVAL
	     An	 undefined  value  was	specified  in  flags;  flags is	set to
	     RS_HIPRI and no control part was supplied;	or the	stream	refer-
	     enced 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  process.	This error condition occurs only with SUS-com-
	     pliant 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.

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

       STREAMS Programming Guide

SunOS 5.9			  17 Oct 1996			     putmsg(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | 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.9>

home | help