Topic       : TOS - The Operating System
Author      : 
Version     : tos.hyp (December 19, 2008)
Subject     : Programmieren/Atari
Nodes       : 3010
Index Size  : 93790
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Title
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File5.12.16  Pmsg                                                      TOS

 Name:         »Pmsg« - Send and receive messages.

 Opcode:       293

 Syntax:       int32_t Pmsg ( int16_t mode, int32_t mbox, void *msg );

 Description:  The function Pmsg sends or receives a message to or 
               from a 'mail box'. The operation to be executed in each 
               case can be set with the bits of the parameter mode. 
               The following apply:

                mode    Operation

                0x0000  Block the process and don't return until a 
                        message is read from the specified mailbox 
                        mbox and placed in the structure pointed to by 
                        msg.
                0x0001  Block the process and don't return until a 
                        process waiting for a message with mailbox ID 
                        mbox has received the message from the 
                        structure pointed to by msg.
                0x0002  Block the process until a process waiting for 
                        a message with the mailbox ID mbox has 
                        received the message held in the structure 
                        pointed to by msg and a return message is 
                        received with mailbox ID 0xffffxxxx (where 
                        xxxx is the PID of the current process).
                0x8000  An OR combination with this value allows the 
                        operation to be performed in a non-blocking 
                        mode.

               The messages are 5 words long, namely two LONGwords and 
               one SHORT (in that order). For this the two LONGs can 
               be filled with any desired information by the process, 
               while the SHORT should have the PID of the sender 
               entered in it.

               After the message has been sent, this SHORT contains 
               the PID of the process that has read the message. 
               Conversely, after reading a message it contains the PID 
               of the processes that wrote the message.

               If mode has the highest bit set and no readers or 
               writers for the mailbox mbox exist, then the value -1 
               will be returned. Otherwise a read operation waits 
               until a message has been written, or a write operation 
               waits until a read process is ready.

               Im mode 2 the writer says that it would like to wait 
               for a reply. The idea behind this is that the process 
               can put itself to sleep, and can be reawakened later by 
               the process that receives the message. This will 
               guarantee that the process that contains the original 
               message is not blocked when writing the reply.

 Return value: The function can return the following results:

                E_OK :    No error has arisen
                EINVFN :  Invalid value for the parameter mode
                -1 :      Bit 15 is set, and Pmsg would block

 Availability: Available when a 'MiNT' cookie with a version of at 
               least 0.90 exists.

 Group:        Process functions

 See also:     Binding