unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

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
       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 pertaining to  putmsg()  also  per-
       tains 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
       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, 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
                       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  multi-
                       plexor.



       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 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:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).   ATTRIBUTE TYPEATTRIBUTE VALUE Interface StabilityStan-
       dard


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)