intermodule_comm/nacl_imc_c.h

   1 /*
   2  * Copyright 2008, Google Inc.
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions are
   7  * met:
   8  *
   9  *     * Redistributions of source code must retain the above copyright
  10  * notice, this list of conditions and the following disclaimer.
  11  *     * Redistributions in binary form must reproduce the above
  12  * copyright notice, this list of conditions and the following disclaimer
  13  * in the documentation and/or other materials provided with the
  14  * distribution.
  15  *     * Neither the name of Google Inc. nor the names of its
  16  * contributors may be used to endorse or promote products derived from
  17  * this software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30  */
  31
  32
  33 // NaCl inter-module communication primitives.
  34 //
  35 // Primitive NaCl socket and shared memory functions which provide a portable
  36 // inter-module communication mechanism between processes on Windows, Mac OS X,
  37 // and Unix variants. On Unix variants, these functions are simple wrapper
  38 // functions for the AF_UNIX domain socket API.
  39
  40 #ifndef NATIVE_CLIENT_INTERMODULE_COMM_NACL_IMC_C_H_
  41 #define NATIVE_CLIENT_INTERMODULE_COMM_NACL_IMC_C_H_
  42
  43 #if NACL_WINDOWS
  44 #include <windows.h>
  45 #endif
  46 #include <sys/types.h>
  47
  48 #ifdef __cplusplus
  49 extern "C" {
  50 #endif  // __cplusplus
  51
  52 // Get the last error message string.
  53 int NaClGetLastErrorString(char* buffer, size_t length);
  54
  55 // NaCl resource descriptor type
  56 // NaCl resource descriptors can be directly used with epoll on Linux, or
  57 // with WaitForMultipleObject on Windows.
  58 // TODO: work out one place for this definition.
  59 #ifndef __nacl_handle_defined
  60 #define __nacl_handle_defined
  61 #if NACL_WINDOWS
  62 typedef HANDLE NaClHandle;
  63 #else
  64 typedef int NaClHandle;
  65 #endif
  66 #endif
  67
  68 #define NACL_INVALID_HANDLE ((NaClHandle) -1)
  69
  70 // The maximum length of the zero-terminated pathname for SocketAddress
  71 #define NACL_PATH_MAX 28            // TBD
  72
  73 // A NaCl socket address is defined as a pathname. The pathname must be a zero-
  74 // terminated character string starting from a character within the ranges A -
  75 // Z or a - z. The pathname is not case sensitive.
  76 typedef struct NaClSocketAddress {
  77   char path[NACL_PATH_MAX];
  78 } NaClSocketAddress;
  79
  80 // I/O vector for the scatter/gather operation used by NaClSendDatagram() and
  81 // NaClReceiveDatagram()
  82 typedef struct NaClIOVec {
  83   void*   base;
  84   size_t  length;
  85 } NaClIOVec;
  86
  87 // The maximum number of handles to be passed by NaClSendDatagram()
  88 #define NACL_HANDLE_COUNT_MAX 8     // TBD
  89
  90 // NaClMessageHeader flags set by NaClReceiveDatagram()
  91 #define NACL_MESSAGE_TRUNCATED 0x1  // The trailing portion of a message was
  92                                     // discarded.
  93 #define NACL_HANDLES_TRUNCATED 0x2  // Not all the handles were received.
  94
  95 // Message header used by NaClSendDatagram() and NaClReceiveDatagram()
  96 typedef struct NaClMessageHeader {
  97   NaClIOVec*  iov;            // scatter/gather array
  98   size_t      iov_length;     // number of elements in iov
  99   NaClHandle* handles;        // array of handles to be transferred
 100   size_t      handle_count;   // number of handles in handles
 101   int         flags;
 102 } NaClMessageHeader;
 103
 104 // Creates a NaCl socket associated with the local address.
 105 // NaClBoundSocket() returns a handle of the newly created bound socket on
 106 // success, and NACL_INVALID_HANDLE on failure.
 107 NaClHandle NaClBoundSocket(const NaClSocketAddress* address);
 108
 109 // Creates an unnamed pair of connected sockets.
 110 // NaClSocketPair() return 0 on success, and -1 on failure.
 111 int NaClSocketPair(NaClHandle pair[2]);
 112
 113 // Closes a NaCl descriptor created by NaCl primitives.
 114 // NaClClose() returns 0 on success, and -1 on failure.
 115 // Note NaCl descriptors must be explicitly closed by NaClClose(). Otherwise,
 116 // the resources of the underlining operating system will not be released
 117 // correctly.
 118 int NaClClose(NaClHandle handle);
 119
 120 // NaClSendDatagram()/NaClReceiveDatagram() flags
 121 #define NACL_DONT_WAIT 0x1  // Enables non-blocking operation
 122
 123 // Checks the last non-blocking operation was failed because no message
 124 // is available in the queue.
 125 // WouldBlock() returns non-zero value if the previous non-blocking
 126 // NaClSendDatagram() or NaClReceiveDatagram() operation would block if
 127 // NACL_DONT_WAIT was not specified.
 128 int NaClWouldBlock();
 129
 130 // Sends a message on a socket.
 131 //
 132 // NaClSendDatagram() and NaClSend() send the message to the remote peer of the
 133 // connection created by SocketPair().
 134 //
 135 // NaClSendDatagramTo() and NaClSendTo() send the message to the socket
 136 // specified by the name. The socket parameter should be a socket created by
 137 // NaClBoundSocket().
 138 //
 139 // The send functions return the number of bytes sent, or -1 upon failure.
 140 //
 141 // If NACL_DONT_WAIT flag is specified with the call and the other peer of
 142 // the socket is unable to receive more data, the function returns -1
 143 // without waiting, and the subsequent NaClWouldBlock() will return non-zero
 144 // value.
 145 //
 146 // Note it is not safe to send messages from the same socket handle by
 147 // multiple threads simultaneously unless the destination address is
 148 // explicitly specified by NaClSendDatagramTo() or NaClSendTo().
 149 int NaClSendDatagram(NaClHandle socket, const NaClMessageHeader* message,
 150                      int flags);
 151 int NaClSendDatagramTo(NaClHandle socket, const NaClMessageHeader* message,
 152                        int flags, const NaClSocketAddress* name);
 153 int NaClSend(NaClHandle socket, const void* buffer, size_t length, int flags);
 154 int NaClSendTo(NaClHandle socket, const void* buffer, size_t length, int flags,
 155                const NaClSocketAddress* name);
 156
 157 // Receives a message from a socket.
 158 // The receive functions return the number of bytes received, or -1 upon
 159 // failure.
 160 //
 161 // If NACL_DONT_WAIT flag is specified with the call and no messages are
 162 // available in the queue, the function returns -1 and the subsequent
 163 // NaClWouldBlock() will return non-zero value. Internally, in this case
 164 // ERROR_PIPE_LISTENING is set to the last error code on Windows and EAGAIN is
 165 // set to errno on Linux.
 166 //
 167 // Note it is not safe to receive messages from the same socket handle
 168 // by multiple threads simultaneously unless the socket handle is created
 169 // by NaClBoundSocket().
 170 int NaClReceiveDatagram(NaClHandle socket, NaClMessageHeader* message,
 171                         int flags);
 172 int NaClReceive(NaClHandle socket, void* buffer, size_t length, int flags);
 173
 174 // Creates a memory object of length bytes.
 175 // NaClCreateMemoryObject() returns a handle of the newly created memory object
 176 // on success, and NACL_INVALID_HANDLE on failure.
 177 // length must be a multiple of allocation granularity given by
 178 // NACL_MAP_PAGESIZE in nacl_config.h.
 179 NaClHandle NaClCreateMemoryObject(size_t length);
 180
 181 // NaClMap() prot bits
 182 #define NACL_PROT_READ    0x1   // Mapped area can be read
 183 #define NACL_PROT_WRITE   0x2   // Mapped area can be written
 184
 185 // NaClMap() flags
 186 #define NACL_MAP_SHARED   0x1   // Create a sharable mapping with other
 187                                 // processes
 188 #define NACL_MAP_PRIVATE  0x2   // Create a private copy-on-write mapping
 189 #define NACL_MAP_FIXED    0x4   // Try to create a mapping at the specified
 190                                 // address
 191
 192 #define NACL_MAP_FAILED   ((void*) -1)
 193
 194 // Maps the specified memory object in the process address space.
 195 // NaClMap() returns a pointer to the mapped area, or NACL_MAP_FAILED upon
 196 // error.
 197 // For prot, the bitwise OR of the NACL_PROT_* bits must be specified.
 198 // For flags, either NACL_MAP_SHARED or NACL_MAP_PRIVATE must be specified.
 199 // If NACL_MAP_FIXED is also set, NaClMap() tries to map the memory object at
 200 // the address specified by start.
 201 void* NaClMap(void* start, size_t length, int prot, int flags,
 202               NaClHandle memory, off_t offset);
 203
 204 // Unmaps the memory objects mapped within the specified process address space
 205 // range.
 206 // NaClUnmap() returns 0 on success, and -1 on failure.
 207 int NaClUnmap(void* start, size_t length);
 208
 209 #ifdef __cplusplus
 210 }
 211 #endif  // __cplusplus
 212
 213 #endif  // NATIVE_CLIENT_INTERMODULE_COMM_NACL_IMC_C_H_