source: rtems/doc/itron3.0/msgbuffer.t @ 086a898a

4.104.114.84.95
Last change on this file since 086a898a was 086a898a, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 16, 1999 at 7:47:37 PM

Added copyright.

  • Property mode set to 100644
File size: 24.5 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1999.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  This is the chapter from the RTEMS ITRON User's Guide that
7@c  documents the services provided by the message buffer
8@c  manager.
9@c
10@c  $Id$
11@c
12
13@chapter Message Buffer Manager
14
15@section Introduction
16
17The message buffer manager provides functions to create, delete, and
18control of message buffers.  This manager is based on the ITRON 3.0
19standard.
20
21The services provided by the message buffer manager are:
22
23@itemize @bullet
24@item @code{cre_mbf} - Create MessageBuffer
25@item @code{del_mbf} - Delete MessageBuffer
26@item @code{snd_mbf} - Send Message to MessageBuffer
27@item @code{psnd_mbf} - Poll and Send Message to MessageBuffer
28@item @code{tsnd_mbf} - Send Message to MessageBuffer with Timeout
29@item @code{rcv_mbf} - Receive Message from MessageBuffer
30@item @code{prcv_mbf} - Poll and Receive Message from MessageBuffer
31@item @code{trcv_mbf} - Receive Message from MessageBuffer with Timeout
32@item @code{ref_mbf} - Reference MessageBuffer Status
33@end itemize
34
35@section Background
36
37@subsection T_CMBF Structure
38
39The T_CMBF structure is used to define the characteristics of a message
40buffer and passed as an argument to the @code{cre_mbf} routine. This
41structure is defined as:
42
43@example
44@group
45
46typedef struct t_cmbf @{
47  VP      exinf;   /* extended information */
48  ATR     mbfatr;  /* message buffer attributes */
49  INT     bufsz;   /* buffer size (in bytes) */
50  INT     maxmsz;  /* maximum message size (in bytes) */
51  /* (CPU and/or implementation-dependent information may also be
52  included) */
53@} T_CMBF;
54
55@end group
56@end example
57
58where the meaning of each field is:
59
60@table @b
61@item exinf
62is for any extended information that the implementation may define. This
63implementation does not use this field.
64
65@item mbfatr
66is the attributes for the message buffer. The only attributes which can
67be specified is whether tasks wait in FIFO (@code{TA_TFIFO}) or priority
68(@code{TA_TPRI}) order.
69
70@item bufsz
71is the size of the message buffer. Since some control data are needed to
72manage each messages in the message buffer, @code{bufsz} is usually
73larger than the total of all message sizes in this buffer.
74
75@item maxmsz
76is the maximum message size.
77
78@end table
79
80@subsection T_RMBF Structure
81
82The T_RMBF structure is filled in by the @code{ref_mbf} routine with
83status and state information of the message buffer. The structure is
84defined as follows:
85
86@example
87@group
88
89typedef struct t_rmbf @{
90  VP      exinf;   /* extended information */
91  BOOL_ID wtsk;    /* waiting task information */
92  BOOL_ID stsk;    /* sending task information */
93  INT     msgsz;   /* message size (in bytes) */
94  INT     frbufsz; /* free buffer size (in bytes) */
95  /* (CPU and/or implementation-dependent information is returned) */
96@} T_RMBF;
97
98@end group
99@end example
100
101@table @b
102
103@item exinf
104is for any extended information that the implementation may define.
105This implementation does not use this field.
106
107@item wtsk
108is TRUE when there is one or more tasks waiting on this message buffer
109to send message. It is FALSE when there is no waiting task. The meaning
110of this field is allowed to vary between ITRON implementations.  It may
111have the ID of a waiting task, the number of tasks waiting, or a boolean
112indication that one or more tasks are waiting.
113
114@item stsk
115is TRUE when there is one or more tasks waiting on this message buffer
116to receive message. It is FALSE when there is no waiting task. The meaning
117of this field is allowed to vary between ITRON implementations.  It may
118have the ID of a waiting task, the number of tasks waiting, or a boolean
119indication that one or more tasks are waiting.
120
121@item msgsz
122is the size of the message that is at the head of the message buffer. If
123there is no message on the message queue, @code{msgsz} will be returned
124as FALSE = 0.
125
126@item frbufsz
127is the amount of free memory in the message buffer.
128
129@end table
130
131@section Operations
132
133@section System Calls
134
135This section details the message buffer manager's services.
136A subsection is dedicated to each of this manager's services
137and describes the calling sequence, related constants, usage,
138and status codes.
139
140@c
141@c  cre_mbf
142@c
143
144@page
145@subsection cre_mbf - Create MessageBuffer
146
147@subheading CALLING SEQUENCE:
148
149@ifset is-C
150@example
151ER cre_mbf(
152  ID mbfid,
153  T_CMBF *pk_cmbf
154);
155@end example
156@end ifset
157
158@ifset is-Ada
159@end ifset
160
161@subheading STATUS CODES:
162
163@code{E_OK} - Normal Completion
164
165@code{E_NOMEM} - Insufficient memory (Memory for control block and/or
166ring buffer cannot be allocted)
167
168@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)
169
170@code{E_RSATR} - Reserved attribute (mbfatr was invalid or could not be
171used)
172
173@code{E_OBJ} - Invalid object state (a messagebuffer of the same ID
174already exists)
175
176@code{E_OACV} - Object access violation (A mbfid less than -4 was
177specified from a user task.  This is implementation dependent.)
178
179@code{E_PAR} - Parameter error (pk_cmbf is invalid or bufsz and/or
180maxmsz is negative or invalid)
181
182@code{EN_OBJNO} - An object number which could not be accessed on the
183target node is specified.
184
185
186@code{EN_CTXID} - Specified an object on another node when the system
187call was issued from a task in dispatch disabled state or from a
188task-independent portion
189
190@code{EN_PAR} - A value outside the range supported by the target node
191and/or transmission packet format was specified as a parameter (a value
192outside supported range was specified for exinf, mbfatr, bufsz and/or
193maxmsz)
194
195@subheading DESCRIPTION:
196
197This routine creates a message buffer on the local node. The message
198buffer is initialized based on the attributes specified in the
199@code{pk_cmbf} structure. The buffer size and the maximum message size
200are determined by the @code{bufsz} and @code{maxmsz} fields in this
201structure.
202
203The @code{mbfatr} field represents attributes of the message
204buffer. If @code{TA_TFIFO} is specified, tasks will be put on the queue
205on a First In-First Out basis. If @code{TA_TPRI} is specified, tasks
206will be placed on the queue according to their priority.
207
208@subheading NOTES:
209
210Multiprocessing is not supported.  Thus none of the "EN_" status codes
211will be returned.
212
213@c
214@c  del_mbf
215@c
216
217@page
218@subsection del_mbf - Delete MessageBuffer
219
220@subheading CALLING SEQUENCE:
221
222@ifset is-C
223@example
224ER del_mbf(
225  ID mbfid
226);
227@end example
228@end ifset
229
230@ifset is-Ada
231@end ifset
232
233@subheading STATUS CODES:
234
235@code{E_OK} - Normal Completion
236
237@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)
238
239@code{E_NOEXS} - Object does not exist (the messagebuffer specified by
240mbfid does not exist)
241
242@code{E_OACV} - Object access violation (A mbfid less than -4 was
243specified from a user task.  This is implementation dependent.)
244
245@code{EN_OBJNO} - An object number which could not be accessed on the
246target node is specified.
247
248@code{EN_CTXID} - Specified an object on another node when the system
249call was issued from a task in dispatch disabled state or from a
250task-independent portion
251
252@subheading DESCRIPTION:
253
254This routine deletes the message buffer specified by @code{mbfid}.
255Issuing this system call releases memory area used for the control block of
256the associated message buffer and the buffer area used for storing messages.
257
258This routine will complete normally even if there are tasks waiting to
259send or receive messages at the message buffer.  In that case, an
260@code{E_DLT} error will be returned to each waiting task.  If there are
261messages still in the message buffer, they will be deleted along with
262the message buffer and no error will result.
263
264@subheading NOTES:
265
266Multiprocessing is not supported.  Thus none of the "EN_" status codes
267will be returned.
268
269@c
270@c  snd_mbf
271@c
272
273@page
274@subsection snd_mbf - Send Message to Message Buffer
275
276@subheading CALLING SEQUENCE:
277
278@ifset is-C
279@example
280ER snd_mbf(
281  ID mbfid,
282  VP msg,
283  INT msgsz
284);
285@end example
286@end ifset
287
288@ifset is-Ada
289@end ifset
290
291@subheading STATUS CODES:
292
293@code{E_OK} - Normal Completion
294
295@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)
296
297@code{E_NOEXS} - Object does not exist (the message buffer specified by
298mbfid does not exist)
299
300@code{E_OACV} - Object access violation (A mbfid less than -4 was
301specified from a user task.  This is implementation dependent.)
302
303@code{E_PAR} - Parameter error (msgsz is 0 or less; msgsz is larger than
304maxmsz; values unsuitable for msg; tmout is -2 or less)
305
306@code{E_DLT} - The object being waited for was deleted (the
307message buffer of interest was deleted while waiting)
308
309@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
310while waiting)
311
312@code{E_CTX} - Context error (issued from task-independent portions or a
313task in dispatch disabled state; implementation dependent for psnd_mbf
314and tsnd_mbf(tmout=TMO_POL))
315
316@code{EN_OBJNO} - An object number which could not be accessed on the
317target node is specified.
318
319@code{EN_CTXID} - Specified an object on another node when the system
320call was issued from a task in dispatch disabled state or from a
321task-independent portion (implementation-dependent; applicable to
322psnd_mbf and tsnd_mbf (tmout=TMO_POL) only)
323
324@code{EN_PAR} - A value outside the range supported by the target node
325and/or transmission packet format was specified as a parameter (a value
326outside supported range was specified for msgsz and/or tmout)
327
328@subheading DESCRIPTION:
329
330This routine sends the message stored at the address given by @code{msg}
331to the message buffer specified by @code{mbfid}.  The size of the
332message is specified by @code{msgsz}; that is, @code{msgsz} number of
333bytes beginning from @code{msg} are copied to the message buffer
334specified by @code{mbfid}.  If the available space in the buffer is not
335enough to include the message given by @code{msg}, the task issuing this
336system call will wait on a send wait queue until more buffer space
337becomes available.
338
339@subheading NOTES:
340
341Multiprocessing is not supported.  Thus none of the "EN_" status codes
342will be returned.
343
344@c
345@c  psnd_mbf
346@c
347
348@page
349@subsection psnd_mbf - Poll and Send Message to Message Buffer
350
351@subheading CALLING SEQUENCE:
352
353@ifset is-C
354@example
355ER ercd =psnd_mbf(
356  ID mbfid,
357  VP msg,
358  INT msgsz
359);
360@end example
361@end ifset
362
363@ifset is-Ada
364@end ifset
365
366@subheading STATUS CODES:
367
368@code{E_OK} - Normal Completion
369
370@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)
371
372@code{E_NOEXS} - Object does not exist (the message buffer specified by
373mbfid does not exist)
374
375@code{E_OACV} - Object access violation (A mbfid less than -4 was
376specified from a user task.  This is implementation dependent.)
377
378@code{E_PAR} - Parameter error (msgsz is 0 or less; msgsz is larger than
379maxmsz; values unsuitable for msg; tmout is -2 or less)
380
381@code{E_DLT} - The object being waited for was deleted (the
382message buffer of interest was deleted while waiting)
383
384@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
385while waiting)
386
387@code{E_TMOUT} - Polling failure or timeout
388
389@code{E_CTX} - Context error (issued from task-independent portions or a
390task in dispatch disabled state; implementation dependent for psnd_mbf
391and tsnd_mbf(tmout=TMO_POL))
392
393@code{EN_OBJNO} - An object number which could not be accessed on the
394target node is specified.
395
396@code{EN_CTXID} - Specified an object on another node when the system
397call was issued from a task in dispatch disabled state or from a
398task-independent portion (implementation-dependent; applicable to
399psnd_mbf and tsnd_mbf (tmout=TMO_POL) only)
400
401@code{EN_PAR} - A value outside the range supported by the target node
402and/or transmission packet format was specified as a parameter (a value
403outside supported range was specified for msgsz and/or tmout)
404
405@subheading DESCRIPTION:
406
407This routine has the same function as @code{snd_mbf} except for the
408waiting feature.  @code{Psnd_mbf} polls whether or not the task should
409wait if @code{snd_mbf} is executed.  The meaning of parameters to
410@code{psnd_mbf} are the same as for @code{snd_mbf}.  The specific
411operations by @code{psnd_mbf} are as follows.
412
413  - If there is enough space in the buffer, processing is the same as
414  @code{snd_mbf}: the message is sent and the system call completes
415  normally.
416
417  - If there is not enough space in the buffer, an @code{E_TMOUT} error
418  is returned to indicate polling failed and the system call finishes.
419  Unlike @code{snd_mbf}, the issuing task does not wait in this case.
420  The status of the message buffer and the message queue remain unchanged.
421
422@subheading NOTES:
423
424Multiprocessing is not supported.  Thus none of the "EN_" status codes
425will be returned.
426
427@c
428@c  tsnd_mbf
429@c
430
431@page
432@subsection tsnd_mbf - Send Message to Message Buffer with Timeout
433
434@subheading CALLING SEQUENCE:
435
436@ifset is-C
437@example
438ER ercd =tsnd_mbf(
439  ID mbfid,
440  VP msg,
441  INT msgsz,
442  TMO tmout
443);
444@end example
445@end ifset
446
447@ifset is-Ada
448@end ifset
449
450@subheading STATUS CODES:
451
452@code{E_OK} - Normal Completion
453
454@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)
455
456@code{E_NOEXS} - Object does not exist (the message buffer specified by
457mbfid does not exist)
458
459@code{E_OACV} - Object access violation (A mbfid less than -4 was
460specified from a user task.  This is implementation dependent.)
461
462@code{E_PAR} - Parameter error (msgsz is 0 or less; msgsz is larger than
463maxmsz; values unsuitable for msg; tmout is -2 or less)
464
465@code{E_DLT} - The object being waited for was deleted (the
466message buffer of interest was deleted while waiting)
467
468@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
469while waiting)
470
471@code{E_TMOUT} - Polling failure or timeout
472
473@code{E_CTX} - Context error (issued from task-independent portions or a
474task in dispatch disabled state; implementation dependent for psnd_mbf
475and tsnd_mbf(tmout=TMO_POL))
476
477@code{EN_OBJNO} - An object number which could not be accessed on the
478target node is specified.
479
480@code{EN_CTXID} - Specified an object on another node when the system
481call was issued from a task in dispatch disabled state or from a
482task-independent portion (implementation-dependent; applicable to
483psnd_mbf and tsnd_mbf (tmout=TMO_POL) only)
484
485@code{EN_PAR} - A value outside the range supported by the target node
486and/or transmission packet format was specified as a parameter (a value
487outside supported range was specified for msgsz and/or tmout)
488
489@subheading DESCRIPTION:
490
491The @code{tsnd_mbf} system call has the same function as @code{snd_mbf}
492with an additional timeout feature.  A maximum wait time (timeout value)
493can be specified using the parameter @code{tmout}.  When a timeout is
494specified, a timeout error, @code{E_TMOUT}, will result and the system
495call will finish if the period specified by @code{tmout} elapses without
496conditions for releasing wait being satisfied (i.e. without sufficient
497buffer space becoming available).
498
499Only positive values can be specified for @code{tmout}.  Specifying
500@code{TMO_POL} = 0 to @code{tsnd_mbf} for @code{tmout} indicates that a
501timeout value of 0 be used, resulting in exactly the same processing as
502@code{psnd_mbf}.  Specifying @code{TMO_FEVR} = -1 to @code{tsnd_mbf} for
503@code{tmout} indicates that an infinite timeout value be used, resulting
504in exactly the same processing as @code{snd_mbf}.
505
506@subheading NOTES:
507
508Multiprocessing is not supported.  Thus none of the "EN_" status codes
509will be returned.
510
511
512@c
513@c  rcv_mbf
514@c
515
516@page
517@subsection rcv_mbf - Receive Message from Message Buffer
518
519@subheading CALLING SEQUENCE:
520
521@ifset is-C
522@example
523ER rcv_mbf(
524  VP msg,
525  INT *p_msgsz,
526  ID mbfid
527);
528@end example
529@end ifset
530
531@ifset is-Ada
532@end ifset
533
534@subheading STATUS CODES:
535
536@code{E_OK} - Normal Completion
537
538@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)
539
540@code{E_NOEXS} - Object does not exist (the message buffer specified by
541mbfid does not exist)
542
543@code{E_OACV} - Object access violation (A mbfid less than -4 was
544specified from a user task.  This is implementation dependent.)
545
546@code{E_PAR} - Parameter error (values unsuitable for msg; tmout is -2
547or less)
548
549@code{E_DLT} - The object being waited for was deleted (the specified
550message buffer was deleted while waiting)
551
552@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
553while waiting)
554
555@code{E_CTX} - Context error (issued from task-independent portions or a
556task in dispatch disabled state)
557
558@code{EN_OBJNO} - An object number which could not be accessed on the
559target node is specified.
560
561@code{EN_PAR} - A value outside the range supported by the target node
562and/or transmission packet format was specified as a parameter (a value
563outside supported range was specified for tmout)
564
565@code{EN_RPAR} - A value outside the range supported by the issuing node
566and/or transmission packet format was returned as a return parameter (msgsz is outside supported range for requesting node)
567
568@subheading DESCRIPTION:
569
570@code{Rcv_mbf} receives the message from the message buffer specified by
571@code{mbfid}, and stores it at the memory location given by @code{msg}.
572In other words, the content of the message at the head of the message
573buffer specified by @code{mbfid} is copied into an area which begins
574from @code{msg} and whose size is @code{msgsz}.
575
576If the message buffer is empty, the task issuing this system call will wait
577on a receive message wait queue until a message arrives.
578
579@subheading NOTES:
580
581Multiprocessing is not supported.  Thus none of the "EN_" status codes
582will be returned.
583
584
585@c
586@c  prcv_mbf
587@c
588
589@page
590@subsection prcv_mbf - Poll and Receive Message from Message Buffer
591
592@subheading CALLING SEQUENCE:
593
594@ifset is-C
595@example
596ER ercd =prcv_mbf(
597  VP msg,
598  INT *p_msgsz,
599  ID mbfid
600);
601@end example
602@end ifset
603
604@ifset is-Ada
605@end ifset
606
607@subheading STATUS CODES:
608
609@code{E_OK} - Normal Completion
610
611@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)
612
613@code{E_NOEXS} - Object does not exist (the message buffer specified by
614mbfid does not exist)
615
616@code{E_OACV} - Object access violation (A mbfid less than -4 was
617specified from a user task.  This is implementation dependent.)
618
619@code{E_PAR} - Parameter error (values unsuitable for msg; tmout is -2
620or less)
621
622@code{E_DLT} - The object being waited for was deleted (the specified
623message buffer was deleted while waiting)
624
625@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
626while waiting)
627
628@code{E_TMOUT} - Polling failure or timeout
629
630@code{E_CTX} - Context error (issued from task-independent portions or a
631task in dispatch disabled state)
632
633@code{EN_OBJNO} - An object number which could not be accessed on the
634target node is specified.
635
636@code{EN_PAR} - A value outside the range supported by the target node
637and/or transmission packet format was specified as a parameter (a value
638outside supported range was specified for tmout)
639
640@code{EN_RPAR} - A value outside the range supported by the issuing node
641and/or transmission packet format was returned as a return parameter (msgsz is outside supported range for requesting node)
642
643
644@subheading DESCRIPTION:
645The @code{prcv_mbf} system call has the same function as @code{rcv_mbf}
646except for the waiting feature.  @code{Prcv_mbf} polls whether or not
647the task should wait if @code{rcv_mbf} is executed.  The meaning of
648parameters to @code{prcv_mbf} are the same as for @code{rcv_mbf}.  The
649specific operations by @code{prcv_mbf} are as follows.
650
651  - If there is a message in the specified message buffer, processing is
652the same as @code{rcv_mbf}: the first message on the message buffer is
653retrieved and the system call completes normally.
654
655  - If there is no message in the specified message buffer, an
656@code{E_TMOUT} error is returned to indicate polling failed and the
657system call finishes.  Unlike @code{rcv_mbf}, the issuing task does not
658wait in this case.  The status of the message buffer remain unchanged.
659
660@subheading NOTES:
661
662Multiprocessing is not supported.  Thus none of the "EN_" status codes
663will be returned.
664
665
666@c
667@c  trcv_mbf
668@c
669
670@page
671@subsection trcv_mbf - Receive Message from Message Buffer with Timeout
672
673@subheading CALLING SEQUENCE:
674
675@ifset is-C
676@example
677ER ercd =trcv_mbf(
678  VP msg,
679  INT *p_msgsz,
680  ID mbfid,
681  TMO tmout
682);
683@end example
684@end ifset
685
686@ifset is-Ada
687@end ifset
688
689@subheading STATUS CODES:
690
691@code{E_OK} - Normal Completion
692
693@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)
694
695@code{E_NOEXS} - Object does not exist (the message buffer specified by
696mbfid does not exist)
697
698@code{E_OACV} - Object access violation (A mbfid less than -4 was
699specified from a user task.  This is implementation dependent.)
700
701@code{E_PAR} - Parameter error (values unsuitable for msg; tmout is -2
702or less)
703
704@code{E_DLT} - The object being waited for was deleted (the specified
705message buffer was deleted while waiting)
706
707@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
708while waiting)
709
710@code{E_TMOUT} - Polling failure or timeout
711
712@code{E_CTX} - Context error (issued from task-independent portions or a
713task in dispatch disabled state)
714
715@code{EN_OBJNO} - An object number which could not be accessed on the
716target node is specified.
717
718@code{EN_PAR} - A value outside the range supported by the target node
719and/or transmission packet format was specified as a parameter (a value
720outside supported range was specified for tmout)
721
722@code{EN_RPAR} - A value outside the range supported by the issuing node
723and/or transmission packet format was returned as a return parameter (msgsz is outside supported range for requesting node)
724
725@subheading DESCRIPTION:
726The @code{trcv_mbf} system call has the same function as @code{rcv_mbf}
727with an additional timeout feature.  A maximum wait time (timeout value)
728can be specified using the parameter @code{tmout}.  When a timeout is
729specified, a timeout error, @code{E_TMOUT}, will result and the system
730call will finish if the period specified by @code{tmout} elapses without
731conditions for releasing wait being satisfied (i.e. without a message
732arriving).
733
734Only positive values can be specified for @code{tmout}.  Specifying
735@code{TMO_POL} = 0 to @code{trcv_mbf} for @code{tmout} indicates that a
736timeout value of 0 be used, resulting in exactly the same processing as
737@code{prcv_mbf}.  Specifying @code{TMO_FEVR} = -1 to @code{trcv_mbf} for
738tmout indicates that an infinite timeout value be used, resulting in
739exactly the same processing as @code{rcv_mbf}.
740
741@subheading NOTES:
742
743Multiprocessing is not supported.  Thus none of the "EN_" status codes
744will be returned.
745
746@c
747@c  ref_mbf
748@c
749
750@page
751@subsection ref_mbf - Reference Message Buffer Status
752
753@subheading CALLING SEQUENCE:
754
755@ifset is-C
756@example
757ER ref_mbf(
758  T_RMBF *pk_rmbf,
759  ID mbfid
760);
761@end example
762@end ifset
763
764@ifset is-Ada
765@end ifset
766
767@subheading STATUS CODES:
768
769@code{E_OK} - Normal Completion
770
771@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)
772
773@code{E_NOEXS} - Object does not exist (the message buffer specified by
774mbfid does not exist)
775
776@code{E_OACV} - Object access violation (A mbfid less than -4 was
777specified from a user task.  This is implementation dependent.)
778
779@code{E_PAR} - Parameter error (the packet address for the return
780parameters could not be used)
781
782@code{EN_OBJNO} - An object number which could not be accessed on the
783target node is specified.
784
785@code{EN_CTXID} - Specified an object on another node when the system
786call was issued from a task in dispatch disabled state or from a
787task-independent portion
788
789@code{EN_RPAR} - A value outside the range supported by the issuing node
790and/or transmission packet format was returned as a return parameter (a
791value outside supported range for exinf, wtsk, stsk, msgsz and/or
792frbufsz on a requesting node)
793
794@subheading DESCRIPTION:
795This system call refers to the state of the message buffer specified by
796@code{mbfid}, and returns information of a task waiting to send a
797message (@code{stsk}), the size of the next message to be received
798(@code{msgsz}), the free buffer size (@code{frbufsz}), information of a
799task waiting to receive a message (@code{wtsk}), and its extended
800information (@code{exinf}).
801
802@code{Wtsk} and @code{stsk} indicate whether or not there is a task
803waiting for the message buffer in question.  If there is no waiting
804task, @code{wtsk} and @code{stsk} are returned as @code{FALSE} = 0.  If
805there is a waiting task, @code{wtsk} and @code{stsk} are returned as
806values other than 0.
807
808An @code{E_NOEXS} error will result if the message buffer specified to
809@code{ref_mbf} does not exist.
810
811The size of the message at the head of the message buffer (the next
812message to be received) is returned to @code{msgsz}.  If there are no
813messages on the message buffer, @code{msgsz} will be returned as
814@code{FALSE} = 0.  A message whose size is zero cannot be sent.
815
816At least one of @code{msgsz} = @code{FALSE} and @code{wtsk} =
817@code{FALSE} is always true in this system call.
818
819@code{Frbufsz} indicates the amount of free memory in the message
820buffer.  This value can be used to know the total approximate size of
821the messages which can be sent to the message buffer.
822
823@subheading NOTES:
824
825Multiprocessing is not supported.  Thus none of the "EN_" status codes
826will be returned.
Note: See TracBrowser for help on using the repository browser.