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 /*
  34  * Nacl inter-module communication primitives.
  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
  41 #ifndef NATIVE_CLIENT_INTERMODULE_COMM_NACL_IMC_C_H_
  42 #define NATIVE_CLIENT_INTERMODULE_COMM_NACL_IMC_C_H_
  43
  44 #if NACL_WINDOWS
  45 #include <windows.h>
  46 #endif
  47 #include <sys/types.h>
  48
  49 #ifdef __cplusplus
  50 extern "C" {
  51 #endif  /* __cplusplus */
  52
  53 /* Get the last error message string. */
  54 int NaClGetLastErrorString(char* buffer, size_t length);
  55
  56
  57
  58 /*
  59  * NaCl resource descriptor type NaCl resource descriptors can be
  60  * directly used with epoll on Linux, or with WaitForMultipleObject on
  61  * Windows.  TODO: work out one place for this definition.
  62  */
  63
  64 #ifndef __nacl_handle_defined
  65 #define __nacl_handle_defined
  66 #if NACL_WINDOWS
  67 typedef HANDLE NaClHandle;
  68 #else
  69 typedef int NaClHandle;
  70 #endif
  71 #endif
  72
  73 #define NACL_INVALID_HANDLE ((NaClHandle) -1)
  74
  75 /* The maximum length of the zero-terminated pathname for SocketAddress */
  76 #define NACL_PATH_MAX 28            /* TBD */
  77
  78 /*
  79  * A NaCl socket address is defined as a pathname. The pathname must
  80  * be a zero- terminated character string starting from a character
  81  * within the ranges A - Z or a - z. The pathname is not case
  82  * sensitive.
  83 */
  84
  85 typedef struct NaClSocketAddress {
  86   char path[NACL_PATH_MAX];
  87 } NaClSocketAddress;
  88
  89 /*
  90  * I/O vector for the scatter/gather operation used by
  91  * NaClSendDatagram() and NaClReceiveDatagram()
  92 */
  93
  94 typedef struct NaClIOVec {
  95   void*   base;
  96   size_t  length;
  97 } NaClIOVec;
  98
  99 /* The maximum number of handles to be passed by NaClSendDatagram() */
 100 #define NACL_HANDLE_COUNT_MAX 8     /* TBD */
 101
 102 /*
 103  * NaClMessageHeader flags set by NaClReceiveDatagram()
 104  */
 105 /* The trailing portion of a message was discarded. */
 106 #define NACL_MESSAGE_TRUNCATED 0x1
 107 /* Not all the handles were received. */
 108 #define NACL_HANDLES_TRUNCATED 0x2
 109
 110 /* Message header used by NaClSendDatagram() and NaClReceiveDatagram() */
 111 typedef struct NaClMessageHeader {
 112   NaClIOVec*  iov;            /* scatter/gather array */
 113   size_t      iov_length;     /* number of elements in iov */
 114   NaClHandle* handles;        /* array of handles to be transferred */
 115   size_t      handle_count;   /* number of handles in handles */
 116   int         flags;
 117 } NaClMessageHeader;
 118
 119 /*
 120  * Creates a NaCl socket associated with the local address.
 121  *
 122  * NaClBoundSocket() returns a handle of the newly created
 123  * bound socket on success, and NACL_INVALID_HANDLE on failure.
 124  */
 125 NaClHandle NaClBoundSocket(const NaClSocketAddress* address);
 126
 127 /*
 128  * Creates an unnamed pair of connected sockets.  NaClSocketPair()
 129  * return 0 on success, and -1 on failure.
 130  */
 131 int NaClSocketPair(NaClHandle pair[2]);
 132
 133 /*
 134  * Closes a NaCl descriptor created by NaCl primitives.
 135  *
 136  * NaClClose() returns 0 on success, and -1 on failure. Note NaCl
 137  * descriptors must be explicitly closed by NaClClose(). Otherwise,
 138  * the resources of the underlining operating system will not be
 139  * released correctly.
 140  */
 141 int NaClClose(NaClHandle handle);
 142
 143 /*
 144  * NaClSendDatagram()/NaClReceiveDatagram() flags
 145  */
 146
 147 #define NACL_DONT_WAIT 0x1  /* Enables non-blocking operation */
 148
 149 /*
 150  * Checks the last non-blocking operation was failed because no
 151  * message is available in the queue.  WouldBlock() returns non-zero
 152  * value if the previous non-blocking NaClSendDatagram() or
 153  * NaClReceiveDatagram() operation would block if NACL_DONT_WAIT was
 154  * not specified.
 155  */
 156 int NaClWouldBlock();
 157
 158 /*
 159  * Sends a message on a socket.
 160  *
 161  * NaClSendDatagram() and NaClSend() send the message to the remote
 162  * peer of the connection created by SocketPair().
 163  *
 164  * NaClSendDatagramTo() and NaClSendTo() send the message to the
 165  * socket specified by the name. The socket parameter should be a
 166  * socket created by NaClBoundSocket().
 167  *
 168  * The send functions return the number of bytes sent, or -1 upon
 169  * failure.  If NACL_DONT_WAIT flag is specified with the call and the
 170  * other peer of the socket is unable to receive more data, the
 171  * function returns -1 without waiting, and the subsequent
 172  * NaClWouldBlock() will return non-zero value.
 173  *
 174  * Note it is not safe to send messages from the same socket handle by
 175  * multiple threads simultaneously unless the destination address is
 176  * explicitly specified by NaClSendDatagramTo() or NaClSendTo().
 177  */
 178 int NaClSendDatagram(NaClHandle socket, const NaClMessageHeader* message,
 179                      int flags);
 180 int NaClSendDatagramTo(NaClHandle socket, const NaClMessageHeader* message,
 181                        int flags, const NaClSocketAddress* name);
 182 int NaClSend(NaClHandle socket, const void* buffer, size_t length, int flags);
 183 int NaClSendTo(NaClHandle socket, const void* buffer, size_t length, int flags,
 184                const NaClSocketAddress* name);
 185
 186 /*
 187  * Receives a message from a socket.
 188  *
 189  * The receive functions return the number of bytes received, or -1 upon failure.
 190  *
 191  * If NACL_DONT_WAIT flag is specified with the call and no messages are
 192  * available in the queue, the function returns -1 and the subsequent
 193  * NaClWouldBlock() will return non-zero value. Internally, in this case
 194  * ERROR_PIPE_LISTENING is set to the last error code on Windows and EAGAIN is
 195  * set to errno on Linux.
 196  *
 197  * Note it is not safe to receive messages from the same socket handle
 198  * by multiple threads simultaneously unless the socket handle is created
 199  * by NaClBoundSocket().
 200  */
 201
 202 int NaClReceiveDatagram(NaClHandle socket, NaClMessageHeader* message,
 203                         int flags);
 204 int NaClReceive(NaClHandle socket, void* buffer, size_t length, int flags);
 205
 206 /*
 207  * Creates a memory object of length bytes.
 208  *
 209  * NaClCreateMemoryObject() returns a handle of the newly created
 210  * memory object on success, and NACL_INVALID_HANDLE on failure.
 211  * length must be a multiple of allocation granularity given by
 212  * NACL_MAP_PAGESIZE in nacl_config.h.
 213  */
 214
 215 NaClHandle NaClCreateMemoryObject(size_t length);
 216
 217 /* NaClMap() prot bits */
 218 #define NACL_PROT_READ    0x1   /* Mapped area can be read */
 219 #define NACL_PROT_WRITE   0x2   /* Mapped area can be written */
 220
 221 /* NaClMap() flags */
 222 #define NACL_MAP_SHARED   0x1   /* Create a sharable mapping with other */
 223                                 /* processes */
 224 #define NACL_MAP_PRIVATE  0x2   /* Create a private copy-on-write mapping */
 225 #define NACL_MAP_FIXED    0x4   /* Try to create a mapping at the specified */
 226                                 /* address */
 227
 228 #define NACL_MAP_FAILED   ((void*) -1)
 229
 230 /*
 231  * Maps the specified memory object in the process address space.
 232  *
 233  * NaClMap() returns a pointer to the mapped area, or NACL_MAP_FAILED upon
 234  * error.
 235  * For prot, the bitwise OR of the NACL_PROT_* bits must be specified.
 236  * For flags, either NACL_MAP_SHARED or NACL_MAP_PRIVATE must be specified.
 237  * If NACL_MAP_FIXED is also set, NaClMap() tries to map the memory object at
 238  * the address specified by start.
 239  */
 240 void* NaClMap(void* start, size_t length, int prot, int flags,
 241               NaClHandle memory, off_t offset);
 242
 243 /*
 244  * Unmaps the memory objects mapped within the specified process
 245  * address space range.
 246  *
 247  * NaClUnmap() returns 0 on success, and -1 on failure.
 248  */
 249 int NaClUnmap(void* start, size_t length);
 250
 251 #ifdef __cplusplus
 252 }
 253 #endif  /* __cplusplus */
 254
 255 #endif  /* NATIVE_CLIENT_INTERMODULE_COMM_NACL_IMC_C_H_ */