include/android/sharedmem.h

   1 /*
   2  * Copyright (C) 2017 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @addtogroup Memory
  19  * @{
  20  */
  21
  22 /**
  23  * @file sharedmem.h
  24  */
  25
  26 #ifndef ANDROID_SHARED_MEMORY_H
  27 #define ANDROID_SHARED_MEMORY_H
  28
  29 #include <stddef.h>
  30
  31 /******************************************************************
  32  *
  33  * IMPORTANT NOTICE:
  34  *
  35  *   This file is part of Android's set of stable system headers
  36  *   exposed by the Android NDK (Native Development Kit).
  37  *
  38  *   Third-party source AND binary code relies on the definitions
  39  *   here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES.
  40  *
  41  *   - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES)
  42  *   - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS
  43  *   - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY
  44  *   - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
  45  */
  46
  47 /**
  48  * Structures and functions for a shared memory buffer that can be shared across process.
  49  */
  50
  51 #ifdef __cplusplus
  52 extern "C" {
  53 #endif
  54
  55 #if __ANDROID_API__ >= __ANDROID_API_O__
  56
  57 /**
  58  * Create a shared memory region.
  59  *
  60  * Create shared memory region and returns an file descriptor.  The resulting file descriptor can be
  61  * mmap'ed to process memory space with PROT_READ | PROT_WRITE | PROT_EXEC. Access to shared memory
  62  * region can be restricted with {@link ASharedMemory_setProt}.
  63  *
  64  * Use close() to release the shared memory region.
  65  *
  66  * \param name an optional name.
  67  * \param size size of the shared memory region
  68  * \return file descriptor that denotes the shared memory; error code on failure.
  69  */
  70 int ASharedMemory_create(const char *name, size_t size);
  71
  72 /**
  73  * Get the size of the shared memory region.
  74  *
  75  * \param fd file descriptor of the shared memory region
  76  * \return size in bytes; 0 if fd is not a valid shared memory file descriptor.
  77  */
  78 size_t ASharedMemory_getSize(int fd);
  79
  80 /**
  81  * Restrict access of shared memory region.
  82  *
  83  * This function restricts access of a shared memory region. Access can only be removed. The effect
  84  * applies globally to all file descriptors in all processes across the system that refer to this
  85  * shared memory region. Existing memory mapped regions are not affected.
  86  *
  87  * It is a common use case to create a shared memory region, map it read/write locally to intialize
  88  * content, and then send the shared memory to another process with read only access. Code example
  89  * as below (error handling omited).
  90  *
  91  *
  92  *     int fd = ASharedMemory_create("memory", 128);
  93  *
  94  *     // By default it has PROT_READ | PROT_WRITE | PROT_EXEC.
  95  *     char *buffer = (char *) mmap(NULL, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
  96  *
  97  *     strcpy(buffer, "This is an example."); // trivially initialize content
  98  *
  99  *     // limit access to read only
 100  *     ASharedMemory_setProt(fd, PROT_READ);
 101  *
 102  *     // share fd with another process here and the other process can only map with PROT_READ.
 103  *
 104  * \param fd   file descriptor of the shared memory region.
 105  * \param prot any bitwise-or'ed combination of PROT_READ, PROT_WRITE, PROT_EXEC denoting
 106  *             updated access. Note access can only be removed, but not added back.
 107  * \return 0 for success, error code on failure.
 108  */
 109 int ASharedMemory_setProt(int fd, int prot);
 110
 111 #endif
 112
 113 #ifdef __cplusplus
 114 };
 115 #endif
 116
 117 #endif // ANDROID_SHARED_MEMORY_H
 118
 119 /** @} */