msgsnap(2) - osol9

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

NAME

6       msgsnap - message queue snapshot operation
7

SYNOPSIS

9       #include <sys/msg.h>
10
11       msgsnap(int msqid, void *buf, size_t bufsz, long msgtyp);
12
13

DESCRIPTION

15       The  msgsnap()  function  reads all of the messages of type msgtyp from
16       the queue associated with the message  queue  identifier  specified  by
17       msqid and places them in the user-defined buffer pointed to by buf.
18
19
20       The  buf  argument  points to a user-defined buffer that on return will
21       contain first a buffer header structure:
22
23         struct msgsnap_head {
24              size_t  msgsnap_size;   /* bytes used/required in the buffer */
25              size_t  msgsnap_nmsg;   /* number of messages in the buffer */
26         };
27
28
29
30       followed by msgsnap_nmsg messages, each of which starts with a  message
31       header:
32
33         struct msgsnap_mhead {
34              size_t  msgsnap_mlen;   /* number of bytes in the message */
35              long    msgsnap_mtype;  /* message type */
36         };
37
38
39
40       and followed by msgsnap_mlen bytes containing the message contents.
41
42
43       Each  subsequent  message header is located at the first byte following
44       the previous message contents, rounded up to a sizeof(size_t) boundary.
45
46
47       The bufsz argument specifies the size  of buf in bytes.   If  bufsz  is
48       less  than sizeof(msgsnap_head), msgsnap() fails with EINVAL.  If bufsz
49       is insufficient to contain all of  the  requested  messages,  msgsnap()
50       succeeds  but  returns with msgsnap_nmsg set to 0 and with msgsnap_size
51       set to the required size of the buffer in bytes.
52
53
54       The msgtyp argument specifies the types of messages requested  as  fol‐
55       lows:
56
57           o      If msgtyp is 0, all of the messages on the queue are read.
58
59           o      If msgtyp is greater than 0, all messages of type msgtyp are
60                  read.
61
62           o      If msgtyp is less than 0, all messages with type  less  than
63                  or equal to the absolute value of msgtyp are read.
64
65
66       The msgsnap() function is a non-destructive operation. Upon completion,
67       no changes are made to the data structures associated with msqid.
68

RETURN VALUES

70       Upon successful completion, msgsnap()  returns  0.   Otherwise,  −1  is
71       returned and errno is set to indicate the error.
72

ERRORS

74       The msgsnap() function will fail if:
75
76       EACCES    Operation  permission  is denied to the calling process.  See
77                 Intro(2).
78
79
80       EINVAL    The msqid argument is not a valid message queue identifier or
81                 the value of bufsz is less than sizeof(struct msgsnap_head).
82
83
84       EFAULT    The buf argument points to an illegal address.
85
86

USAGE

88       The  msgsnap()  function  returns  a  snapshot of messages on a message
89       queue at one point in time.  The queue contents can change  immediately
90       following return from msgsnap().
91

EXAMPLES

93       Example 1 msgsnap() example
94
95
96       This  is  sample C code indicating how to use the msgsnap function (see
97       msgids(2)).
98
99
100         void
101         process_msgid(int msqid)
102         {
103              size_t bufsize;
104              struct msgsnap_head *buf;
105              struct msgsnap_mhead *mhead;
106              int i;
107
108              /* allocate a minimum-size buffer */
109              buf = malloc(bufsize = sizeof(struct msgsnap_head));
110
111              /* read all of the messages from the queue */
112              for (;;) {
113                   if (msgsnap(msqid, buf, bufsize, 0) != 0) {
114                        perror("msgsnap");
115                             free(buf);
116                             return;
117                   }
118                   if (bufsize >= buf->msgsnap_size)  /* we got them all */
119                        break;
120                   /* we need a bigger buffer */
121                   buf = realloc(buf, bufsize = buf->msgsnap_size);
122              }
123
124              /* process each message in the queue (there may be none) */
125              mhead = (struct msgsnap_mhead *)(buf + 1);  /* first message */
126              for (i = 0; i < buf->msgsnap_nmsg; i++) {
127                   size_t mlen = mhead->msgsnap_mlen;
128
129                   /* process the message contents */
130                   process_message(mhead->msgsnap_mtype, (char *)(mhead+1), mlen);
131
132                   /* advance to the next message header */
133                   mhead = (struct msgsnap_mhead *)
134                        ((char *)mhead + sizeof(struct msgsnap_mhead) +
135                        ((mlen + sizeof(size_t) - 1) & ~(sizeof(size_t) - 1)));
136              }
137
138              free(buf);
139         }
140
141

ATTRIBUTES

143       See attributes(5) for descriptions of the following attributes:
144
145
146
147
148       ┌─────────────────────────────┬─────────────────────────────┐
149       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
150       ├─────────────────────────────┼─────────────────────────────┤
151       │MT-Level                     │Async-Signal-Safe            │
152       └─────────────────────────────┴─────────────────────────────┘
153