unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



putmsg(2)							    putmsg(2)



NAME

  putmsg, putpmsg - Send a message on a	Stream

LIBRARY

  Standard C Library (libc)

SYNOPSIS

  #include <&lt;stropts.h>&gt;

  int putmsg(
	  int fd,
	  const	struct strbuf *ctlbuf,
	  const	struct strbuf *databuf,
	  int flags);

  int putpmsg(
	  int fd,
	  const	struct strbuf *ctlbuf,
	  const	struct strbuf *databuf,
	  int band,
	  int flags);

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  putmsg(), putpmsg(): XSH5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  fd	    Specifies a	file descriptor	that references	an open	Stream.

  ctlbuf    Points to a	strbuf structure that describes	the control part, if
	    any, of the	message. This strbuf structure is described in the
	    DESCRIPTION	section.

  databuf   Points to a	strbuf structure that holds the	data part, if any, of
	    the	message. This strbuf structure is described in the DESCRIP-
	    TION section.

  band	    Specifies the priority band.

  flags	    Specifies the type of message that should be sent.



DESCRIPTION

  The putmsg() and putpmsg() functions send messages to	the STREAMS file.
  These	messages are generated from user-provided buffer(s), and must contain
  a control part and/or	a data part.  The open Stream specifies	the format
  and semantics	of the message's control and data parts.  The control and
  data parts of	the message are	placed into separate buffers, pointed at by
  cltbuf and databuf respectively.  The	putpmsg() function provides more con-
  trol over how	messages are sent.  With this function,	you can	send messages
  in different priority	bands.	Except where specified,	all information	that
  applies to the putmsg() function also	applies	to the putpmsg() function.

  The ctlbuf and databuf parameters each point to a strbuf structure that
  contains three members.  This	structure is defined in	<&lt;sys/stropts.h>&gt;	as:

       struct strbuf {
	   int maxlen;	       /* max buffer length */
	   int len;	       /* length of data */
	   char	*buf	       /* pointer to buffer */
       };

  The members are:

  maxlen    Specifies the maximum number of bytes buf can hold.	 This field
	    is not used	by either the putmsg() or putpmsg() function.

  buf	    Points to the buffer where the control information is to reside.

  len	    Specifies the number of bytes to be	sent.

  A message can	contain	a control part or a data part, or both,	depending on
  what is to be	sent.  To send one or the other, the corresponding ctlbuf or
  databuf parameter must be a non-null pointer and the len field of the
  corresponding	strbuf structure must have a value of 0	(zero) or greater.  A
  data or control part is not sent if its respective databuf or	ctlbuf param-
  eter is a null pointer, or if	the corresponding structure's len field	is
  set to -1.

  One of the major differences between the putmsg() and	putpmsg() function,
  in addition to the band parameter, is	how the	flag parameter is used to
  send messages.  The putmsg() function	sends messages as follows:

    +  If you set the flags parameter to a value of 0 (zero), a	normal mes-
       sage (priority band equal to 0 (zero)) is sent.

    +  If you set the flags parameter to RS_HIPRI and a	control	part is
       specified, the control and data (if present) is sent as a high prior-
       ity message.

    +  If you set the flags parameter to RS_HIPRI and a	control	part is	not
       specified, putmsg() fails.

    +  If you set the flags parameter to 0 (zero) and both the control part
       and the data part of not	specified, no message is sent and a value of
       0 (zero)	is returned.

  The putpmsg()	function flags parameter is a bitmask with the mutually
  exclusive flags MSG_HIPRI and	MSG_BAND defined.  The putpmsg() function
  sends	messages as follows:

    +  If you set flags	to MSG_BAND, the control and/or	data part is sent on
       the priority band specified by the band parameter.

    +  If you set the flags parameter to MSG_HIPRI, set	the band parameter to
       0 (zero), and specify a control part, the control and data (if
       present)	is sent	as a high-priority message.

    +  If you set the flags parameter to MSG_HIPRI, and	either no control
       part is specified or band is set	to a non-zero value, the putpmsg()
       function	fails.

    +  If you set flags	to MSG_BAND, and both a	control	part and data are not
       specified, no message is	sent and a value of 0 (zero) is	returned.

    +  If you set the flags parameter to 0 (zero), putpmsg() fails.

  Unless the message is	a high priority	one, the putmsg() function generally
  blocks if the	Stream write queue is full.  This is because of	internal flow
  control conditions.  The putmsg() function does not block on this condition
  for high priority messages.  However,	for other messages, if the O_NDELAY
  or O_NONBLOCK	flag is	set for	the write() operation, the putmsg() function
  will not block when the write	queue is full.	Instead, it fails.

  In addition, unless the system runs out of internal resources, the putmsg()
  function will	block while waiting for	the availability of message blocks in
  the Stream.	In this	instance, neither the message priority nor the asser-
  tion of the O_NDELAY or O_NONBLOCK flag matter.  Partial messages are	not
  sent.

  [Tru64 UNIX]	Current	industry standards do not define the O_NDELAY flag.
  It is	included in the	preceding paragraphs for System	V compatibility.

NOTES

  [Tru64 UNIX]	When compiled in the X/Open UNIX environment, calls to the
  putmsg() and putpmsg() functions are internally renamed by prepending	_E to
  the function name. When you are debugging a module that includes the
  putmsg() or putpmsg()	function and for which _XOPEN_SOURCE_EXTENDED has
  been defined,	use _Eputmsg to	refer to the putmsg() call, and	_Eputpmsg to
  refer	to the putpmsg() call.	See standards(5) for further information.

RETURN VALUES

  Upon successful completion, the putmsg() functions return a value of 0
  (zero). Otherwise, they return a value of -1 and errno is set	to indicate
  an error.

ERRORS

  The putmsg() function	fails if the Stream head has processed a STREAM	error
  message before either	of these functions is called.  In this instance, the
  STREAMS error	message	contains the value of the returned error.

  In addition, if any of the following conditions occurs, the putmsg() func-
  tion sets errno to the corresponding value.

  [EAGAIN]  For	a non-priority message,	the O_NDELAY or	the O_NONBLOCK flag
	    is set, and	the Stream write queue is determined to	be full
	    because of the internal flow control conditions.

	    [Tru64 UNIX]  Current industry standards do	not define the
	    O_NDELAY flag.  It is included in the preceding paragraphs for
	    System V compatibility.

	    The	system could not allocate buffers for the message to be
	    created.

  [EBADF]   The	fd parameter is	not invalid for	writing.

  [EINTR]   The	putmsg() function was interrupted by a signal that was
	    caught.

  [EINVAL]  An undefined message was specified in the flags parameter.

	    For	the putmsg() function, the flags parameter is RS_HIPRI or
	    MSG_HIPRI, and the ctlbuf len parameter is less than 0 (zero).

	    For	the putpmsg() function,	the flags parameter is MSG_HIPRI and
	    the	ctlbuf len parameter is	less than 0 (zero)

	    [Tru64 UNIX]  For the putpmsg() function, the flags	parameter is
	    MSG_HIPRI and the band parameter is	not 0 (zero); or the flags
	    parameter is MSG_BAND and the band parameter is greater than the
	    system minimum.

	    The	Stream specified by the	fd parameter is	linked under a multi-
	    plexor.

  [ENOSR]   The	system could not allocate buffers for the message that was to
	    be created because of insufficient Streams memory resources.

  [ENOSTR]  A Stream is	not associated with the	fd parameter.

  [EPIPE]   The	other end of a Streams-based piped referred to by the fd
	    parameter is closed.  A SIGPIPE signal is generated	for the	cal-
	    ling process.

  [ENXIO]   A hangup condition for the specified Stream	was generated down-
	    stream.

  [ERANGE]  The	size of	the control part of a message is larger	than the max-
	    imum configured size of the	message's control part;	or the data
	    part of a message is larger	than the maximum configured size of
	    the	message's data part; or	the data part size of the message
	    does not conform to	the range indicated by the maximum and
	    minimum packet sizes of the	topmost	Stream module.

RELATED	INFORMATION

  Functions: getmsg(2),	poll(2), read(2), write(2)

  Interfaces: streamio(7)

  Standards: standards(5)