putmsg man page on OSF1

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
OSF1 logo
[printable version]

putmsg(2)							     putmsg(2)

NAME
       putmsg, putpmsg - Send a message on a Stream

SYNOPSIS
       #include <stropts.h>

       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 );

LIBRARY
       Standard C Library (libc)

STANDARDS
       Interfaces  documented on this reference page conform to industry stan‐
       dards as follows:

       putmsg(), putpmsg(): XSH4.0, XSH4.2, XSH5.0

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

PARAMETERS
       Specifies  a file descriptor that references an open Stream.  Points to
       a strbuf structure that describes the control part, if any, of the mes‐
       sage.  This  strbuf  structure is described in the DESCRIPTION section.
       Points to a strbuf structure that holds the data part, if any,  of  the
       message.	  This	strbuf	structure is described in the DESCRIPTION sec‐
       tion.  Specifies the priority band.  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  control over how messages are sent. With this function,
       you can send messages in different priority bands. Except where	speci‐
       fied,  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 <sys/stropts.h>
       as:

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

       The members are: Specifies the maximum number of bytes  buf  can	 hold.
       This  field  is	not used by either the putmsg() or putpmsg() function.
       Points to the buffer where the control information is to reside.	 Spec‐
       ifies 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 ctl‐
       buf  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 parameter is a null pointer, or if the	 corresponding	struc‐
       ture's len field is set to -1.

       One  of	the major differences between the putmsg() and putpmsg() func‐
       tion, in addition to the band parameter, is how the flags 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 message
       (priority band equal to 0 (zero)) is sent.  If you set the flags param‐
       eter to RS_HIPRI and a control part is specified, the control and  data
       (if  present) is sent as a high priority 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 options MSG_HIPRI and MSG_BAND defined. The  putpmsg()	 func‐
       tion  sends messages as follows: If you set flags to MSG_BAND, the con‐
       trol 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 gener‐
       ally  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 mes‐
       sages, if the O_NDELAY or O_NONBLOCK flag is set for the write() opera‐
       tion,  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 mes‐
       sage blocks in the Stream. In this instance, neither the message prior‐
       ity nor the assertion of the O_NDELAY or O_NONBLOCK option matter. Par‐
       tial 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 compati‐
       bility.

NOTES
       [Tru64 UNIX]  When compiled in the X/Open UNIX  environment,  calls  to
       the putmsg() and putpmsg() functions are internally renamed by prepend‐
       ing _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 stan‐
       dards(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 indi‐
       cate 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()
       function sets errno to the corresponding	 value.	  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  con‐
       trol 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 cre‐
	      ated.  The  fd  parameter	 is  not  invalid  for	writing.   The
	      putmsg()	function  was interrupted by a signal that was caught.
	      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 mul‐
	      tiplexor.	 The system could not allocate buffers for the message
	      that  was	 to  be created because of insufficient Streams memory
	      resources.  A Stream is not associated with  the	fd  parameter.
	      The  other  end  of  a Streams-based piped referred to by the fd
	      parameter is closed. A SIGPIPE signal is generated for the call‐
	      ing  process.   A	 hangup condition for the specified Stream was
	      generated downstream.  The size of the control part of a message
	      is larger than the maximum configured size of the message's con‐
	      trol part; or the data part of a message is larger than the max‐
	      imum  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.

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

       Interfaces: streamio(7)

       Standards: standards(5)

       Network Programmer's Guide

								     putmsg(2)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OSF1

List of man pages available for OSF1

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net