aurorafw.android.platform.sharedmem source code

1 /*
2                                     __
3                                    / _|
4   __ _ _   _ _ __ ___  _ __ __ _  | |_ ___  ___ ___
5  / _` | | | | '__/ _ \| '__/ _` | |  _/ _ \/ __/ __|
6 | (_| | |_| | | | (_) | | | (_| | | || (_) \__ \__ \
7  \__,_|\__,_|_|  \___/|_|  \__,_| |_| \___/|___/___/
8 
9 Copyright (C) 2017 The Android Open Source Project.
10 Copyright (C) 2018-2019 Aurora Free Open Source Software.
11 
12 This file is part of the Aurora Free Open Source Software. This
13 organization promote free and open source software that you can
14 redistribute and/or modify under the terms of the GNU Lesser General
15 Public License Version 3 as published by the Free Software Foundation or
16 (at your option) any later version approved by the Aurora Free Open Source
17 Software Organization. The license is available in the package root path
18 as 'LICENSE' file. Please review the following information to ensure the
19 GNU Lesser General Public License version 3 requirements will be met:
20 https://www.gnu.org/licenses/lgpl.html .
21 
22 Alternatively, this file may be used under the terms of the GNU General
23 Public License version 3 or later as published by the Free Software
24 Foundation. Please review the following information to ensure the GNU
25 General Public License requirements will be met:
26 https://www.gnu.org/licenses/gpl-3.0.html.
27 
28 NOTE: All products, services or anything associated to trademarks and
29 service marks used or referenced on this file are the property of their
30 respective companies/owners or its subsidiaries. Other names and brands
31 may be claimed as the property of others.
32 
33 For more info about intellectual property visit: aurorafoss.org or
34 directly send an email to: contact (at) aurorafoss.org .
35 
36 This file has bindings for an existing code, part of The Android Open Source
37 Project implementation. Check it out at android.googlesource.com .
38 */
39 
40 module aurorafw.android.platform.sharedmem;
41 
42 /**
43  * @addtogroup Memory
44  * @{
45  */
46 
47 /**
48  * @file aurorafw/android/platform/sharedmem.d
49  * @brief Shared memory buffers that can be shared across process.
50  */
51 
52 version (Android):
53 extern (C):
54 @system:
55 nothrow:
56 @nogc:
57 
58 /******************************************************************
59  *
60  * IMPORTANT NOTICE:
61  *
62  *   This file is part of Android's set of stable system headers
63  *   exposed by the Android NDK (Native Development Kit).
64  *
65  *   Third-party source AND binary code relies on the definitions
66  *   here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES.
67  *
68  *   - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES)
69  *   - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS
70  *   - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY
71  *   - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
72  */
73 
74 /**
75  * Create a shared memory region.
76  *
77  * Create shared memory region and returns an file descriptor.  The resulting file descriptor can be
78  * mmap'ed to process memory space with PROT_READ | PROT_WRITE | PROT_EXEC. Access to shared memory
79  * region can be restricted with {@link ASharedMemory_setProt}.
80  *
81  * Use close() to release the shared memory region.
82  *
83  * Available since API level 26.
84  *
85  * \param name an optional name.
86  * \param size size of the shared memory region
87  * \return file descriptor that denotes the shared memory; error code on failure.
88  */
89 int ASharedMemory_create (const(char)* name, size_t size);
90 
91 /**
92  * Get the size of the shared memory region.
93  *
94  * Available since API level 26.
95  *
96  * \param fd file descriptor of the shared memory region
97  * \return size in bytes; 0 if fd is not a valid shared memory file descriptor.
98  */
99 size_t ASharedMemory_getSize (int fd);
100 
101 /**
102  * Restrict access of shared memory region.
103  *
104  * This function restricts access of a shared memory region. Access can only be removed. The effect
105  * applies globally to all file descriptors in all processes across the system that refer to this
106  * shared memory region. Existing memory mapped regions are not affected.
107  *
108  * It is a common use case to create a shared memory region, map it read/write locally to intialize
109  * content, and then send the shared memory to another process with read only access. Code example
110  * as below (error handling omited).
111  *
112  *
113  *     int fd = ASharedMemory_create("memory", 128);
114  *
115  *     // By default it has PROT_READ | PROT_WRITE | PROT_EXEC.
116  *     char *buffer = (char *) mmap(NULL, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
117  *
118  *     strcpy(buffer, "This is an example."); // trivially initialize content
119  *
120  *     // limit access to read only
121  *     ASharedMemory_setProt(fd, PROT_READ);
122  *
123  *     // share fd with another process here and the other process can only map with PROT_READ.
124  *
125  * Available since API level 26.
126  *
127  * \param fd   file descriptor of the shared memory region.
128  * \param prot any bitwise-or'ed combination of PROT_READ, PROT_WRITE, PROT_EXEC denoting
129  *             updated access. Note access can only be removed, but not added back.
130  * \return 0 for success, error code on failure.
131  */
132 int ASharedMemory_setProt (int fd, int prot);
133 
134 // __ANDROID_API__ >= 26
135 
136 // ANDROID_SHARED_MEMORY_H
137 
138 /** @} */