msgrcv(2) - osol9

1msgrcv(2)                        System Calls                        msgrcv(2)
2
3
4

NAME

6       msgrcv - message receive operation
7

SYNOPSIS

9       #include <sys/msg.h>
10
11       ssize_t msgrcv(int msqid, void *msgp, size_t msgsz,
12            long int msgtyp, int msgflg);
13
14

DESCRIPTION

16       The  msgrcv()  function  reads a message from the queue associated with
17       the message queue identifier specified by msqid and places  it  in  the
18       user-defined buffer pointed to by msgp.
19
20
21       The  msgp  argument  points  to a user-defined buffer that must contain
22       first a field of type long int that will specify the type of  the  mes‐
23       sage, and then a data portion that will hold the data bytes of the mes‐
24       sage. The structure below is an example of what this user-defined  buf‐
25       fer might look like:
26
27         struct mymsg {
28                 long int    mtype;     /* message type */
29                 char        mtext[1];  /* message text */
30         }
31
32
33
34       The  mtype  member  is  the received message's type as specified by the
35       sending process.
36
37
38       The mtext member is the text of the message.
39
40
41       The  msgsz argument specifies the size in bytes of mtext. The  received
42       message  is  truncated  to  msgsz  bytes if it is larger than msgsz and
43       (msgflg&MSG_NOERROR) is non-zero. The truncated part of the message  is
44       lost  and  no  indication  of  the  truncation  is given to the calling
45       process.
46
47
48       The msgtyp argument specifies the type of message requested as follows:
49
50           o      If msgtyp is 0, the first message on the queue is received.
51
52           o      If msgtyp is greater than 0, the first message of type  msg‐
53                  typ is received.
54
55           o      If  msgtyp  is  less than 0, the first message of the lowest
56                  type that is less than or equal to  the  absolute  value  of
57                  msgtyp is received.
58
59
60       The  msgflg  argument specifies which of the following actions is to be
61       taken if a message of the desired type is not on the queue:
62
63           o      If (msgflg&IPC_NOWAIT) is non-zero, the calling process will
64                  return  immediately  with a return value of −1 and errno set
65                  to ENOMSG.
66
67           o      If (msgflg&IPC_NOWAIT) is 0, the calling process  will  sus‐
68                  pend execution until one of the following occurs:
69
70               o      A message of the desired type is placed on the queue.
71
72               o      The  message  queue identifier msqid is removed from the
73                      system (see msgctl(2)); when this occurs, errno  is  set
74                      equal to EIDRM and −1 is returned.
75
76               o      The  calling  process  receives  a  signal that is to be
77                      caught; in this case a message is not received  and  the
78                      calling  process  resumes  execution  in the manner pre‐
79                      scribed in sigaction(2).
80
81
82       Upon successful  completion,  the  following  actions  are  taken  with
83       respect to the data structure associated with msqid (see Intro(2)):
84
85           o      msg_qnum is decremented by 1.
86
87           o      msg_lrpid  is  set  equal  to  the process ID of the calling
88                  process.
89
90           o      msg_rtime is set equal to the current time.
91

RETURN VALUES

93       Upon successful completion, msgrcv() returns a value equal to the  num‐
94       ber  of  bytes  actually placed into the buffer mtext. Otherwise, −1 is
95       returned, no message is received, and errno  is  set  to  indicate  the
96       error.
97

ERRORS

99       The msgrcv() function will fail if:
100
101       E2BIG     The    value   of   mtext   is   greater   than   msgsz   and
102                 (msgflg&MSG_NOERROR) is 0.
103
104
105       EACCES    Operation permission is denied to the calling  process.   See
106                 Intro(2).
107
108
109       EIDRM     The  message  queue identifier msqid is removed from the sys‐
110                 tem.
111
112
113       EINTR     The msgrcv() function was interrupted by a signal.
114
115
116       EINVAL    The msqid argument is not a valid message queue identifier.
117
118
119       ENOMSG    The queue does not contain a message of the desired type  and
120                 (msgflg&IPC_NOWAIT) is non-zero.
121
122
123
124       The msgrcv() function may fail if:
125
126        EFAULT    The msgp argument points to an illegal address.
127
128

USAGE

130       The  value passed as the msgp argument should be converted to type void
131       *.
132

ATTRIBUTES

134       See attributes(5) for descriptions of the following attributes:
135
136
137
138
139       ┌─────────────────────────────┬─────────────────────────────┐
140       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
141       ├─────────────────────────────┼─────────────────────────────┤
142       │Interface Stability          │Standard                     │
143       └─────────────────────────────┴─────────────────────────────┘
144