1/* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. 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#ifndef APR_SHM_H 18#define APR_SHM_H 19 20/** 21 * @file apr_shm.h 22 * @brief APR Shared Memory Routines 23 */ 24 25#include "apr.h" 26#include "apr_pools.h" 27#include "apr_errno.h" 28#include "apr_perms_set.h" 29 30#ifdef __cplusplus 31extern "C" { 32#endif /* __cplusplus */ 33 34/** 35 * @defgroup apr_shm Shared Memory Routines 36 * @ingroup APR 37 * @{ 38 */ 39 40/** 41 * Private, platform-specific data struture representing a shared memory 42 * segment. 43 */ 44typedef struct apr_shm_t apr_shm_t; 45 46/** 47 * Create and make accessible a shared memory segment with default 48 * properties. 49 * @param m The shared memory structure to create. 50 * @param reqsize The desired size of the segment. 51 * @param filename The file to use for shared memory on platforms that 52 * require it. 53 * @param pool the pool from which to allocate the shared memory 54 * structure. 55 * @remark A note about Anonymous vs. Named shared memory segments: 56 * Not all plaforms support anonymous shared memory segments, but in 57 * some cases it is prefered over other types of shared memory 58 * implementations. Passing a NULL 'file' parameter to this function 59 * will cause the subsystem to use anonymous shared memory segments. 60 * If such a system is not available, APR_ENOTIMPL is returned. 61 * @remark A note about allocation sizes: 62 * On some platforms it is necessary to store some metainformation 63 * about the segment within the actual segment. In order to supply 64 * the caller with the requested size it may be necessary for the 65 * implementation to request a slightly greater segment length 66 * from the subsystem. In all cases, the apr_shm_baseaddr_get() 67 * function will return the first usable byte of memory. 68 * 69 */ 70APR_DECLARE(apr_status_t) apr_shm_create(apr_shm_t **m, 71 apr_size_t reqsize, 72 const char *filename, 73 apr_pool_t *pool); 74 75/** 76 * Special processing flags for apr_shm_create_ex() and apr_shm_attach_ex(). 77 */ 78#define APR_SHM_NS_LOCAL 1 /* Create or attach to named shared memory 79 * segment in the "Local" namespace on 80 * Windows. (Ignored on other platforms.) 81 * By default, the "Global" namespace is 82 * used for privileged processes and the 83 * "Local" namespace is used otherwise. 84 */ 85#define APR_SHM_NS_GLOBAL 2 /* Create or attach to named shared memory 86 * segment in the "Global" namespace on 87 * Windows. (Ignored on other platforms.) 88 */ 89 90/** 91 * Create and make accessible a shared memory segment with platform- 92 * specific processing. 93 * @param m The shared memory structure to create. 94 * @param reqsize The desired size of the segment. 95 * @param filename The file to use for shared memory on platforms that 96 * require it. 97 * @param pool the pool from which to allocate the shared memory 98 * structure. 99 * @param flags mask of APR_SHM_* (defined above) 100 * @remark A note about Anonymous vs. Named shared memory segments: 101 * Not all plaforms support anonymous shared memory segments, but in 102 * some cases it is prefered over other types of shared memory 103 * implementations. Passing a NULL 'file' parameter to this function 104 * will cause the subsystem to use anonymous shared memory segments. 105 * If such a system is not available, APR_ENOTIMPL is returned. 106 * @remark A note about allocation sizes: 107 * On some platforms it is necessary to store some metainformation 108 * about the segment within the actual segment. In order to supply 109 * the caller with the requested size it may be necessary for the 110 * implementation to request a slightly greater segment length 111 * from the subsystem. In all cases, the apr_shm_baseaddr_get() 112 * function will return the first usable byte of memory. 113 * 114 */ 115APR_DECLARE(apr_status_t) apr_shm_create_ex(apr_shm_t **m, 116 apr_size_t reqsize, 117 const char *filename, 118 apr_pool_t *pool, 119 apr_int32_t flags); 120 121/** 122 * Remove named resource associated with a shared memory segment, 123 * preventing attachments to the resource, but not destroying it. 124 * @param filename The filename associated with shared-memory segment which 125 * needs to be removed 126 * @param pool The pool used for file operations 127 * @remark This function is only supported on platforms which support 128 * name-based shared memory segments, and will return APR_ENOTIMPL on 129 * platforms without such support. Removing the file while the shm 130 * is in use is not entirely portable, caller may use this to enhance 131 * obscurity of the resource, but be prepared for the call to fail, 132 * and for concurrent attempts to create a resource of the same name 133 * to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) 134 * also removes the named resource. 135 */ 136APR_DECLARE(apr_status_t) apr_shm_remove(const char *filename, 137 apr_pool_t *pool); 138 139/** 140 * Delete named resource associated with a shared memory segment, 141 * preventing attachments to the resource. 142 * @param m The shared memory segment structure to delete. 143 * @remark This function is only supported on platforms which support 144 * name-based shared memory segments, and will return APR_ENOTIMPL on 145 * platforms without such support. Removing the file while the shm 146 * is in use is not entirely portable, caller may use this to enhance 147 * obscurity of the resource, but be prepared for the call to fail, 148 * and for concurrent attempts to create a resource of the same name 149 * to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) 150 * also removes the named resource. 151 */ 152APR_DECLARE(apr_status_t) apr_shm_delete(apr_shm_t *m); 153 154/** 155 * Destroy a shared memory segment and associated memory. 156 * @param m The shared memory segment structure to destroy. 157 */ 158APR_DECLARE(apr_status_t) apr_shm_destroy(apr_shm_t *m); 159 160/** 161 * Attach to a shared memory segment that was created 162 * by another process. 163 * @param m The shared memory structure to create. 164 * @param filename The file used to create the original segment. 165 * (This MUST match the original filename.) 166 * @param pool the pool from which to allocate the shared memory 167 * structure for this process. 168 */ 169APR_DECLARE(apr_status_t) apr_shm_attach(apr_shm_t **m, 170 const char *filename, 171 apr_pool_t *pool); 172 173/** 174 * Attach to a shared memory segment that was created 175 * by another process, with platform-specific processing. 176 * @param m The shared memory structure to create. 177 * @param filename The file used to create the original segment. 178 * (This MUST match the original filename.) 179 * @param pool the pool from which to allocate the shared memory 180 * structure for this process. 181 * @param flags mask of APR_SHM_* (defined above) 182 */ 183APR_DECLARE(apr_status_t) apr_shm_attach_ex(apr_shm_t **m, 184 const char *filename, 185 apr_pool_t *pool, 186 apr_int32_t flags); 187 188/** 189 * Detach from a shared memory segment without destroying it. 190 * @param m The shared memory structure representing the segment 191 * to detach from. 192 */ 193APR_DECLARE(apr_status_t) apr_shm_detach(apr_shm_t *m); 194 195/** 196 * Retrieve the base address of the shared memory segment. 197 * NOTE: This address is only usable within the callers address 198 * space, since this API does not guarantee that other attaching 199 * processes will maintain the same address mapping. 200 * @param m The shared memory segment from which to retrieve 201 * the base address. 202 * @return address, aligned by APR_ALIGN_DEFAULT. 203 */ 204APR_DECLARE(void *) apr_shm_baseaddr_get(const apr_shm_t *m); 205 206/** 207 * Retrieve the length of a shared memory segment in bytes. 208 * @param m The shared memory segment from which to retrieve 209 * the segment length. 210 */ 211APR_DECLARE(apr_size_t) apr_shm_size_get(const apr_shm_t *m); 212 213/** 214 * Set shared memory permissions. 215 */ 216APR_PERMS_SET_IMPLEMENT(shm); 217 218/** 219 * Get the pool used by this shared memory segment. 220 */ 221APR_POOL_DECLARE_ACCESSOR(shm); 222 223/** @} */ 224 225#ifdef __cplusplus 226} 227#endif 228 229#endif /* APR_SHM_T */ 230