getmsg man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

getmsg(2)							     getmsg(2)

NAME
       getmsg, getpmsg - receive next message from a STREAMS file

SYNOPSIS
DESCRIPTION
       The function retrieves the contents of a message located at the head of
       the stream head read queue associated with a STREAMS  file  and	places
       the  contents  into one or more buffers.	 The message contains either a
       data part, a control part, or both.  The data and control parts of  the
       message	are  placed  into  separate  buffers, as described below.  The
       semantics of each part is defined by the originator of the message.

       The function does the same thing as but provides finer control over the
       priority	 of  the  messages received.  Except where noted, all require‐
       ments on also pertain to

       The fildes argument specifies a file descriptor referencing a  STREAMS-
       based file.

       The  ctlptr  and	 dataptr arguments each point to a structure, in which
       the buf member points to a buffer in which the data or control informa‐
       tion  is to be placed, and the maxlen member indicates the maximum num‐
       ber of bytes this buffer can hold.  On return, the len member  contains
       the  number  of bytes of data or control information actually received.
       The len member is set to 0 if there is a zero-length  control  or  data
       part  and len is set to -1 if no data or control information is present
       in the message.

       When is called, flagsp should point to an integer  that	indicates  the
       type of message the process is able to receive.	This is described fur‐
       ther below.

       The ctlptr argument is used to hold the control part  of	 the  message,
       and  dataptr  is	 used to hold the data part of the message.  If ctlptr
       (or dataptr) is a null pointer or the maxlen members is −1, the control
       (or  data)  part	 of  the  message  is not processed and is left on the
       stream head read queue, and if the ctlptr (or dataptr) is  not  a  null
       pointer,	 len is set to −1.  If the maxlen member is set to 0 and there
       is a zero-length control (or  data)  part,  that	 zero-length  part  is
       removed	from the read queue and len is set to 0.  If the maxlen member
       is set to 0 and there are more than 0 bytes of control (or data) infor‐
       mation, that information is left on the read queue and len is set to 0.
       If the maxlen member in ctlptr (or dataptr) is less  than  the  control
       (or  data)  part	 of  the message, maxlen bytes are retrieved.  In this
       case, the remainder of the message is left  on  the  stream  head  read
       queue and a on-zero return value is provided.

       By  default,  processes	the first available message on the stream head
       read queue.  However, a process may choose to retrieve only high-prior‐
       ity  messages  by  setting  the integer pointed to by flagsp to In this
       case, will only process the next message if it is a high-priority  mes‐
       sage.   When the integer pointed to by flagsp is 0, any message will be
       retrieved.  In this case, on return, the integer pointed to  by	flagsp
       will  be	 set  to if a high-priority message was retrieved, or 0 other‐
       wise.

       For the flags are different.  The flagsp argument points to  a  bitmask
       with  the  following  mutually-exclusive	 flags defined.	 and Like pro‐
       cesses the first available message on the stream head  read  queue.   A
       process	may  choose  to retrieve only high-priority message by setting
       the integer pointed to by flagsp to and the integer pointed to by bandp
       to  0.	In this case, will only process the next message if is a high-
       priority message.  In  a	 similar  manner,  a  process  may  choose  to
       retrieve a message from a particular priority band by setting the inte‐
       ger pointed to by flagsp to and the integer pointed to by bandp to  the
       priority	 band  of  interest.  In this case, will only process the next
       message if it is in a priority band equal  to,  or  greater  than,  the
       integer pointed to by bandp, or if it is a high-priority message.  If a
       process just wants to get the first message off the queue, the  integer
       pointed	to  by	bandp  should  be set to 0.  On return, if the message
       retrieved was a high-priority message, the integer pointed to by flagsp
       will  be	 set  to and the integer pointed to by bandp will be set to 0.
       Otherwise, the integer pointed to by flagsp will	 be  set  to  and  the
       integer	pointed	 to  by	 bandp will be set to the priority band of the
       message.

       If is not set, and will block until a message of the type specified  by
       flagsp  is available at the front of the stream head read queue.	 If is
       set and a message of the specified type is not present at the front  of
       the read queue, and fail and set to [EAGAIN].

       If  a  hangup  occurs  on  the  stream  from  which  messages are to be
       retrieved, and continue to operate normally, as described above,	 until
       the  stream head read queue is empty.  Thereafter, they return 0 in the
       len members of ctlptr and dataptr.

RETURN VALUE
       Upon successful completion, and return a non-negative value.   A	 value
       of  0  indicates	 that  a full message was read successfully.  A return
       value of	 indicates  that  more	control	 information  is  waiting  for
       retrieval.   A  return value of indicates that more data is waiting for
       retrieval.  A return value of the bitwise logical OR of	and  indicates
       that  both  types of information remain.	 Subsequent and calls retrieve
       the remainder of the message.  However, if a message of higher priority
       has  come  in  on  the  stream  head  read  queue,  the next call to or
       retrieves that higher-priority message before retrieving the  remainder
       of the previously-received partial message.

       Upon failure, and return -1 and set to indicate the error.

ERRORS
       The and functions will fail if:

	      [EAGAIN]	     The flag is set and no messages are available.

	      [EBADF]	     The  fildes argument is not a valid file descrip‐
			     tor open for reading.

	      [EBADMSG]	     The queued message to be read is not valid for or
			     or	 a  pending  file  descriptor is at the stream
			     head.

	      [EINTR]	     A signal was caught during or

	      [EINVAL]	     An illegal value was specified by flagsp, or  the
			     stream  or	 multiplexor  referenced  by fildes is
			     linked (directly or indirectly) downstream from a
			     multiplexor.

	      [ENOSTR]	     A stream is not associated with fildes.

SEE ALSO
       poll(2),	 putmsg(2),  read(2), write(2), thread_safety(5), streamio(7),
       <stropts.h>.

								     getmsg(2)
[top]

List of man pages available for HP-UX

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