summaryrefslogtreecommitdiffstats
path: root/doc/itron3.0/msgbuffer.t
blob: fa0704191c81f7d1d006472f4071ba25237afe33 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
@c
@c  COPYRIGHT (c) 1988-2002.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved.
@c
@c  This is the chapter from the RTEMS ITRON User's Guide that
@c  documents the services provided by the message buffer
@c  manager.
@c
@c  $Id$
@c

@chapter Message Buffer Manager

@section Introduction

The message buffer manager provides functions to create, delete, and
control of message buffers.  This manager is based on the ITRON 3.0
standard. 

The services provided by the message buffer manager are:

@itemize @bullet
@item @code{cre_mbf} - Create MessageBuffer
@item @code{del_mbf} - Delete MessageBuffer
@item @code{snd_mbf} - Send Message to MessageBuffer
@item @code{psnd_mbf} - Poll and Send Message to MessageBuffer
@item @code{tsnd_mbf} - Send Message to MessageBuffer with Timeout
@item @code{rcv_mbf} - Receive Message from MessageBuffer
@item @code{prcv_mbf} - Poll and Receive Message from MessageBuffer
@item @code{trcv_mbf} - Receive Message from MessageBuffer with Timeout
@item @code{ref_mbf} - Reference MessageBuffer Status
@end itemize

@section Background

@subsection T_CMBF Structure

The T_CMBF structure is used to define the characteristics of a message
buffer and passed as an argument to the @code{cre_mbf} routine. This
structure is defined as:

@example
@group

typedef struct t_cmbf @{
  VP      exinf;   /* extended information */
  ATR     mbfatr;  /* message buffer attributes */
  INT     bufsz;   /* buffer size (in bytes) */
  INT     maxmsz;  /* maximum message size (in bytes) */
  /* (CPU and/or implementation-dependent information may also be
  included) */
@} T_CMBF;

@end group
@end example

where the meaning of each field is:

@table @b
@item exinf
is for any extended information that the implementation may define. This
implementation does not use this field.

@item mbfatr
is the attributes for the message buffer. The only attributes which can
be specified is whether tasks wait in FIFO (@code{TA_TFIFO}) or priority
(@code{TA_TPRI}) order.

@item bufsz
is the size of the message buffer. Since some control data are needed to
manage each messages in the message buffer, @code{bufsz} is usually
larger than the total of all message sizes in this buffer.

@item maxmsz
is the maximum message size.

@end table

@subsection T_RMBF Structure

The T_RMBF structure is filled in by the @code{ref_mbf} routine with
status and state information of the message buffer. The structure is
defined as follows:

@example
@group

typedef struct t_rmbf @{
  VP      exinf;   /* extended information */
  BOOL_ID wtsk;    /* waiting task information */
  BOOL_ID stsk;    /* sending task information */
  INT     msgsz;   /* message size (in bytes) */
  INT     frbufsz; /* free buffer size (in bytes) */
  /* (CPU and/or implementation-dependent information is returned) */
@} T_RMBF;

@end group
@end example

@table @b

@item exinf
is for any extended information that the implementation may define.
This implementation does not use this field.

@item wtsk
is TRUE when there is one or more tasks waiting on this message buffer
to send message. It is FALSE when there is no waiting task. The meaning
of this field is allowed to vary between ITRON implementations.  It may
have the ID of a waiting task, the number of tasks waiting, or a boolean
indication that one or more tasks are waiting.

@item stsk
is TRUE when there is one or more tasks waiting on this message buffer
to receive message. It is FALSE when there is no waiting task. The meaning
of this field is allowed to vary between ITRON implementations.  It may
have the ID of a waiting task, the number of tasks waiting, or a boolean
indication that one or more tasks are waiting.

@item msgsz
is the size of the message that is at the head of the message buffer. If
there is no message on the message queue, @code{msgsz} will be returned
as FALSE = 0.

@item frbufsz
is the amount of free memory in the message buffer. 

@end table

@section Operations

@section System Calls

This section details the message buffer manager's services.
A subsection is dedicated to each of this manager's services
and describes the calling sequence, related constants, usage,
and status codes.

@c
@c  cre_mbf
@c

@page
@subsection cre_mbf - Create MessageBuffer

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER cre_mbf(
  ID mbfid,
  T_CMBF *pk_cmbf
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_NOMEM} - Insufficient memory (Memory for control block and/or
ring buffer cannot be allocted)

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_RSATR} - Reserved attribute (mbfatr was invalid or could not be
used)

@code{E_OBJ} - Invalid object state (a messagebuffer of the same ID
already exists)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (pk_cmbf is invalid or bufsz and/or
maxmsz is negative or invalid) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.


@code{EN_CTXID} - Specified an object on another node when the system
call was issued from a task in dispatch disabled state or from a
task-independent portion

@code{EN_PAR} - A value outside the range supported by the target node
and/or transmission packet format was specified as a parameter (a value
outside supported range was specified for exinf, mbfatr, bufsz and/or
maxmsz) 

@subheading DESCRIPTION:

This routine creates a message buffer on the local node. The message
buffer is initialized based on the attributes specified in the
@code{pk_cmbf} structure. The buffer size and the maximum message size
are determined by the @code{bufsz} and @code{maxmsz} fields in this
structure. 

The @code{mbfatr} field represents attributes of the message
buffer. If @code{TA_TFIFO} is specified, tasks will be put on the queue
on a First In-First Out basis. If @code{TA_TPRI} is specified, tasks
will be placed on the queue according to their priority.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.

@c
@c  del_mbf
@c

@page
@subsection del_mbf - Delete MessageBuffer

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER del_mbf(
  ID mbfid
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the messagebuffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_CTXID} - Specified an object on another node when the system
call was issued from a task in dispatch disabled state or from a
task-independent portion 

@subheading DESCRIPTION:

This routine deletes the message buffer specified by @code{mbfid}. 
Issuing this system call releases memory area used for the control block of
the associated message buffer and the buffer area used for storing messages.

This routine will complete normally even if there are tasks waiting to
send or receive messages at the message buffer.  In that case, an
@code{E_DLT} error will be returned to each waiting task.  If there are
messages still in the message buffer, they will be deleted along with
the message buffer and no error will result.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.

@c
@c  snd_mbf
@c

@page
@subsection snd_mbf - Send Message to Message Buffer

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER snd_mbf(
  ID mbfid,
  VP msg,
  INT msgsz
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the message buffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (msgsz is 0 or less; msgsz is larger than
maxmsz; values unsuitable for msg; tmout is -2 or less) 

@code{E_DLT} - The object being waited for was deleted (the
message buffer of interest was deleted while waiting)

@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
while waiting)

@code{E_CTX} - Context error (issued from task-independent portions or a
task in dispatch disabled state; implementation dependent for psnd_mbf
and tsnd_mbf(tmout=TMO_POL)) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_CTXID} - Specified an object on another node when the system
call was issued from a task in dispatch disabled state or from a
task-independent portion (implementation-dependent; applicable to
psnd_mbf and tsnd_mbf (tmout=TMO_POL) only) 

@code{EN_PAR} - A value outside the range supported by the target node
and/or transmission packet format was specified as a parameter (a value
outside supported range was specified for msgsz and/or tmout) 

@subheading DESCRIPTION:

This routine sends the message stored at the address given by @code{msg}
to the message buffer specified by @code{mbfid}.  The size of the
message is specified by @code{msgsz}; that is, @code{msgsz} number of
bytes beginning from @code{msg} are copied to the message buffer
specified by @code{mbfid}.  If the available space in the buffer is not
enough to include the message given by @code{msg}, the task issuing this
system call will wait on a send wait queue until more buffer space
becomes available.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.

@c
@c  psnd_mbf
@c

@page
@subsection psnd_mbf - Poll and Send Message to Message Buffer

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER ercd =psnd_mbf(
  ID mbfid,
  VP msg,
  INT msgsz
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the message buffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (msgsz is 0 or less; msgsz is larger than
maxmsz; values unsuitable for msg; tmout is -2 or less) 

@code{E_DLT} - The object being waited for was deleted (the
message buffer of interest was deleted while waiting)

@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
while waiting)

@code{E_TMOUT} - Polling failure or timeout

@code{E_CTX} - Context error (issued from task-independent portions or a
task in dispatch disabled state; implementation dependent for psnd_mbf
and tsnd_mbf(tmout=TMO_POL)) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_CTXID} - Specified an object on another node when the system
call was issued from a task in dispatch disabled state or from a
task-independent portion (implementation-dependent; applicable to
psnd_mbf and tsnd_mbf (tmout=TMO_POL) only) 

@code{EN_PAR} - A value outside the range supported by the target node
and/or transmission packet format was specified as a parameter (a value
outside supported range was specified for msgsz and/or tmout) 

@subheading DESCRIPTION:

This routine has the same function as @code{snd_mbf} except for the
waiting feature.  @code{Psnd_mbf} polls whether or not the task should
wait if @code{snd_mbf} is executed.  The meaning of parameters to
@code{psnd_mbf} are the same as for @code{snd_mbf}.  The specific
operations by @code{psnd_mbf} are as follows.

  - If there is enough space in the buffer, processing is the same as
  @code{snd_mbf}: the message is sent and the system call completes
  normally.

  - If there is not enough space in the buffer, an @code{E_TMOUT} error
  is returned to indicate polling failed and the system call finishes.
  Unlike @code{snd_mbf}, the issuing task does not wait in this case.
  The status of the message buffer and the message queue remain unchanged.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.

@c
@c  tsnd_mbf
@c

@page
@subsection tsnd_mbf - Send Message to Message Buffer with Timeout

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER ercd =tsnd_mbf(
  ID mbfid,
  VP msg,
  INT msgsz,
  TMO tmout
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the message buffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (msgsz is 0 or less; msgsz is larger than
maxmsz; values unsuitable for msg; tmout is -2 or less) 

@code{E_DLT} - The object being waited for was deleted (the
message buffer of interest was deleted while waiting)

@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
while waiting)

@code{E_TMOUT} - Polling failure or timeout

@code{E_CTX} - Context error (issued from task-independent portions or a
task in dispatch disabled state; implementation dependent for psnd_mbf
and tsnd_mbf(tmout=TMO_POL)) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_CTXID} - Specified an object on another node when the system
call was issued from a task in dispatch disabled state or from a
task-independent portion (implementation-dependent; applicable to
psnd_mbf and tsnd_mbf (tmout=TMO_POL) only) 

@code{EN_PAR} - A value outside the range supported by the target node
and/or transmission packet format was specified as a parameter (a value
outside supported range was specified for msgsz and/or tmout) 

@subheading DESCRIPTION:

The @code{tsnd_mbf} system call has the same function as @code{snd_mbf}
with an additional timeout feature.  A maximum wait time (timeout value)
can be specified using the parameter @code{tmout}.  When a timeout is
specified, a timeout error, @code{E_TMOUT}, will result and the system
call will finish if the period specified by @code{tmout} elapses without
conditions for releasing wait being satisfied (i.e. without sufficient
buffer space becoming available).

Only positive values can be specified for @code{tmout}.  Specifying
@code{TMO_POL} = 0 to @code{tsnd_mbf} for @code{tmout} indicates that a
timeout value of 0 be used, resulting in exactly the same processing as
@code{psnd_mbf}.  Specifying @code{TMO_FEVR} = -1 to @code{tsnd_mbf} for
@code{tmout} indicates that an infinite timeout value be used, resulting
in exactly the same processing as @code{snd_mbf}.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.


@c
@c  rcv_mbf
@c

@page
@subsection rcv_mbf - Receive Message from Message Buffer

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER rcv_mbf(
  VP msg,
  INT *p_msgsz,
  ID mbfid
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the message buffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (values unsuitable for msg; tmout is -2
or less) 

@code{E_DLT} - The object being waited for was deleted (the specified
message buffer was deleted while waiting)

@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
while waiting)

@code{E_CTX} - Context error (issued from task-independent portions or a
task in dispatch disabled state) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_PAR} - A value outside the range supported by the target node
and/or transmission packet format was specified as a parameter (a value
outside supported range was specified for tmout)

@code{EN_RPAR} - A value outside the range supported by the issuing node
and/or transmission packet format was returned as a return parameter (msgsz is outside supported range for requesting node)

@subheading DESCRIPTION:

@code{Rcv_mbf} receives the message from the message buffer specified by
@code{mbfid}, and stores it at the memory location given by @code{msg}.
In other words, the content of the message at the head of the message
buffer specified by @code{mbfid} is copied into an area which begins
from @code{msg} and whose size is @code{msgsz}.

If the message buffer is empty, the task issuing this system call will wait
on a receive message wait queue until a message arrives.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.


@c
@c  prcv_mbf
@c

@page
@subsection prcv_mbf - Poll and Receive Message from Message Buffer

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER ercd =prcv_mbf(
  VP msg,
  INT *p_msgsz,
  ID mbfid
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the message buffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (values unsuitable for msg; tmout is -2
or less) 

@code{E_DLT} - The object being waited for was deleted (the specified
message buffer was deleted while waiting)

@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
while waiting)

@code{E_TMOUT} - Polling failure or timeout

@code{E_CTX} - Context error (issued from task-independent portions or a
task in dispatch disabled state) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_PAR} - A value outside the range supported by the target node
and/or transmission packet format was specified as a parameter (a value
outside supported range was specified for tmout)

@code{EN_RPAR} - A value outside the range supported by the issuing node
and/or transmission packet format was returned as a return parameter (msgsz is outside supported range for requesting node)


@subheading DESCRIPTION:
The @code{prcv_mbf} system call has the same function as @code{rcv_mbf}
except for the waiting feature.  @code{Prcv_mbf} polls whether or not
the task should wait if @code{rcv_mbf} is executed.  The meaning of
parameters to @code{prcv_mbf} are the same as for @code{rcv_mbf}.  The
specific operations by @code{prcv_mbf} are as follows.

  - If there is a message in the specified message buffer, processing is
the same as @code{rcv_mbf}: the first message on the message buffer is
retrieved and the system call completes normally.

  - If there is no message in the specified message buffer, an
@code{E_TMOUT} error is returned to indicate polling failed and the
system call finishes.  Unlike @code{rcv_mbf}, the issuing task does not
wait in this case.  The status of the message buffer remain unchanged.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.


@c
@c  trcv_mbf
@c

@page
@subsection trcv_mbf - Receive Message from Message Buffer with Timeout

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER ercd =trcv_mbf(
  VP msg,
  INT *p_msgsz,
  ID mbfid,
  TMO tmout
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the message buffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (values unsuitable for msg; tmout is -2
or less) 

@code{E_DLT} - The object being waited for was deleted (the specified
message buffer was deleted while waiting)

@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
while waiting)

@code{E_TMOUT} - Polling failure or timeout

@code{E_CTX} - Context error (issued from task-independent portions or a
task in dispatch disabled state) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_PAR} - A value outside the range supported by the target node
and/or transmission packet format was specified as a parameter (a value
outside supported range was specified for tmout)

@code{EN_RPAR} - A value outside the range supported by the issuing node
and/or transmission packet format was returned as a return parameter (msgsz is outside supported range for requesting node)

@subheading DESCRIPTION:
The @code{trcv_mbf} system call has the same function as @code{rcv_mbf}
with an additional timeout feature.  A maximum wait time (timeout value)
can be specified using the parameter @code{tmout}.  When a timeout is
specified, a timeout error, @code{E_TMOUT}, will result and the system
call will finish if the period specified by @code{tmout} elapses without
conditions for releasing wait being satisfied (i.e. without a message
arriving).

Only positive values can be specified for @code{tmout}.  Specifying
@code{TMO_POL} = 0 to @code{trcv_mbf} for @code{tmout} indicates that a
timeout value of 0 be used, resulting in exactly the same processing as
@code{prcv_mbf}.  Specifying @code{TMO_FEVR} = -1 to @code{trcv_mbf} for
tmout indicates that an infinite timeout value be used, resulting in
exactly the same processing as @code{rcv_mbf}.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.

@c
@c  ref_mbf
@c

@page
@subsection ref_mbf - Reference Message Buffer Status

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER ref_mbf(
  T_RMBF *pk_rmbf,
  ID mbfid
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the message buffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (the packet address for the return
parameters could not be used) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_CTXID} - Specified an object on another node when the system
call was issued from a task in dispatch disabled state or from a
task-independent portion

@code{EN_RPAR} - A value outside the range supported by the issuing node
and/or transmission packet format was returned as a return parameter (a
value outside supported range for exinf, wtsk, stsk, msgsz and/or
frbufsz on a requesting node) 

@subheading DESCRIPTION:
This system call refers to the state of the message buffer specified by
@code{mbfid}, and returns information of a task waiting to send a
message (@code{stsk}), the size of the next message to be received
(@code{msgsz}), the free buffer size (@code{frbufsz}), information of a
task waiting to receive a message (@code{wtsk}), and its extended
information (@code{exinf}).

@code{Wtsk} and @code{stsk} indicate whether or not there is a task
waiting for the message buffer in question.  If there is no waiting
task, @code{wtsk} and @code{stsk} are returned as @code{FALSE} = 0.  If
there is a waiting task, @code{wtsk} and @code{stsk} are returned as
values other than 0.

An @code{E_NOEXS} error will result if the message buffer specified to
@code{ref_mbf} does not exist.

The size of the message at the head of the message buffer (the next
message to be received) is returned to @code{msgsz}.  If there are no
messages on the message buffer, @code{msgsz} will be returned as
@code{FALSE} = 0.  A message whose size is zero cannot be sent.

At least one of @code{msgsz} = @code{FALSE} and @code{wtsk} =
@code{FALSE} is always true in this system call.

@code{Frbufsz} indicates the amount of free memory in the message
buffer.  This value can be used to know the total approximate size of
the messages which can be sent to the message buffer.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.