1234285Sdim/* Licensed to the Apache Software Foundation (ASF) under one or more 2234285Sdim * contributor license agreements. See the NOTICE file distributed with 3234285Sdim * this work for additional information regarding copyright ownership. 4234285Sdim * The ASF licenses this file to You under the Apache License, Version 2.0 5234285Sdim * (the "License"); you may not use this file except in compliance with 6234285Sdim * the License. You may obtain a copy of the License at 7234285Sdim * 8234285Sdim * http://www.apache.org/licenses/LICENSE-2.0 9234285Sdim * 10239462Sdim * Unless required by applicable law or agreed to in writing, software 11239462Sdim * distributed under the License is distributed on an "AS IS" BASIS, 12239462Sdim * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13234285Sdim * See the License for the specific language governing permissions and 14234285Sdim * limitations under the License. 15234285Sdim */ 16234285Sdim 17234285Sdim#ifndef APR_SHM_H 18234285Sdim#define APR_SHM_H 19234285Sdim 20249423Sdim/** 21249423Sdim * @file apr_shm.h 22249423Sdim * @brief APR Shared Memory Routines 23234285Sdim */ 24234285Sdim 25234285Sdim#include "apr.h" 26234285Sdim#include "apr_pools.h" 27234285Sdim#include "apr_errno.h" 28234285Sdim 29234285Sdim#ifdef __cplusplus 30234285Sdimextern "C" { 31234285Sdim#endif /* __cplusplus */ 32234285Sdim 33234285Sdim/** 34234285Sdim * @defgroup apr_shm Shared Memory Routines 35234285Sdim * @ingroup APR 36234285Sdim * @{ 37249423Sdim */ 38249423Sdim 39249423Sdim/** 40234285Sdim * Private, platform-specific data struture representing a shared memory 41234285Sdim * segment. 42234285Sdim */ 43234285Sdimtypedef struct apr_shm_t apr_shm_t; 44234285Sdim 45234285Sdim/** 46234285Sdim * Create and make accessible a shared memory segment with default 47234285Sdim * properties. 48234285Sdim * @param m The shared memory structure to create. 49234285Sdim * @param reqsize The desired size of the segment. 50234285Sdim * @param filename The file to use for shared memory on platforms that 51234285Sdim * require it. 52234285Sdim * @param pool the pool from which to allocate the shared memory 53234285Sdim * structure. 54234285Sdim * @remark A note about Anonymous vs. Named shared memory segments: 55234285Sdim * Not all plaforms support anonymous shared memory segments, but in 56234285Sdim * some cases it is prefered over other types of shared memory 57234285Sdim * implementations. Passing a NULL 'file' parameter to this function 58234285Sdim * will cause the subsystem to use anonymous shared memory segments. 59234285Sdim * If such a system is not available, APR_ENOTIMPL is returned. 60234285Sdim * @remark A note about allocation sizes: 61234285Sdim * On some platforms it is necessary to store some metainformation 62234285Sdim * about the segment within the actual segment. In order to supply 63234285Sdim * the caller with the requested size it may be necessary for the 64234285Sdim * implementation to request a slightly greater segment length 65234285Sdim * from the subsystem. In all cases, the apr_shm_baseaddr_get() 66234285Sdim * function will return the first usable byte of memory. 67234285Sdim * 68234285Sdim */ 69234285SdimAPR_DECLARE(apr_status_t) apr_shm_create(apr_shm_t **m, 70234285Sdim apr_size_t reqsize, 71234285Sdim const char *filename, 72234285Sdim apr_pool_t *pool); 73234285Sdim 74234285Sdim/** 75234285Sdim * Special processing flags for apr_shm_create_ex() and apr_shm_attach_ex(). 76234285Sdim */ 77234285Sdim#define APR_SHM_NS_LOCAL 1 /* Create or attach to named shared memory 78234285Sdim * segment in the "Local" namespace on 79234285Sdim * Windows. (Ignored on other platforms.) 80234285Sdim * By default, the "Global" namespace is 81234285Sdim * used for privileged processes and the 82234285Sdim * "Local" namespace is used otherwise. 83234285Sdim */ 84234285Sdim#define APR_SHM_NS_GLOBAL 2 /* Create or attach to named shared memory 85234285Sdim * segment in the "Global" namespace on 86234285Sdim * Windows. (Ignored on other platforms.) 87234285Sdim */ 88239462Sdim 89234285Sdim/** 90234285Sdim * Create and make accessible a shared memory segment with platform- 91234285Sdim * specific processing. 92234285Sdim * @param m The shared memory structure to create. 93234285Sdim * @param reqsize The desired size of the segment. 94234285Sdim * @param filename The file to use for shared memory on platforms that 95234285Sdim * require it. 96234285Sdim * @param pool the pool from which to allocate the shared memory 97234285Sdim * structure. 98234285Sdim * @param flags mask of APR_SHM_* (defined above) 99239462Sdim * @remark A note about Anonymous vs. Named shared memory segments: 100234285Sdim * Not all plaforms support anonymous shared memory segments, but in 101234285Sdim * some cases it is prefered over other types of shared memory 102234285Sdim * implementations. Passing a NULL 'file' parameter to this function 103234285Sdim * will cause the subsystem to use anonymous shared memory segments. 104234285Sdim * If such a system is not available, APR_ENOTIMPL is returned. 105234285Sdim * @remark A note about allocation sizes: 106234285Sdim * On some platforms it is necessary to store some metainformation 107239462Sdim * about the segment within the actual segment. In order to supply 108239462Sdim * the caller with the requested size it may be necessary for the 109234285Sdim * implementation to request a slightly greater segment length 110234285Sdim * from the subsystem. In all cases, the apr_shm_baseaddr_get() 111234285Sdim * function will return the first usable byte of memory. 112234285Sdim * 113234285Sdim */ 114234285SdimAPR_DECLARE(apr_status_t) apr_shm_create_ex(apr_shm_t **m, 115234285Sdim apr_size_t reqsize, 116239462Sdim const char *filename, 117239462Sdim apr_pool_t *pool, 118234285Sdim apr_int32_t flags); 119234285Sdim 120234285Sdim/** 121234285Sdim * Remove named resource associated with a shared memory segment, 122234285Sdim * preventing attachments to the resource, but not destroying it. 123234285Sdim * @param filename The filename associated with shared-memory segment which 124234285Sdim * needs to be removed 125234285Sdim * @param pool The pool used for file operations 126234285Sdim * @remark This function is only supported on platforms which support 127234285Sdim * name-based shared memory segments, and will return APR_ENOTIMPL on 128234285Sdim * platforms without such support. Removing the file while the shm 129234285Sdim * is in use is not entirely portable, caller may use this to enhance 130234285Sdim * obscurity of the resource, but be prepared for the call to fail, 131234285Sdim * and for concurrent attempts to create a resource of the same name 132234285Sdim * to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) 133234285Sdim * also removes the named resource. 134234285Sdim */ 135234285SdimAPR_DECLARE(apr_status_t) apr_shm_remove(const char *filename, 136234285Sdim apr_pool_t *pool); 137234285Sdim 138234285Sdim/** 139234285Sdim * Destroy a shared memory segment and associated memory. 140234285Sdim * @param m The shared memory segment structure to destroy. 141234285Sdim */ 142234285SdimAPR_DECLARE(apr_status_t) apr_shm_destroy(apr_shm_t *m); 143234285Sdim 144234285Sdim/** 145234285Sdim * Attach to a shared memory segment that was created 146234285Sdim * by another process. 147234285Sdim * @param m The shared memory structure to create. 148234285Sdim * @param filename The file used to create the original segment. 149234285Sdim * (This MUST match the original filename.) 150234285Sdim * @param pool the pool from which to allocate the shared memory 151234285Sdim * structure for this process. 152234285Sdim */ 153234285SdimAPR_DECLARE(apr_status_t) apr_shm_attach(apr_shm_t **m, 154234285Sdim const char *filename, 155234285Sdim apr_pool_t *pool); 156234285Sdim 157234285Sdim/** 158234285Sdim * Attach to a shared memory segment that was created 159234285Sdim * by another process, with platform-specific processing. 160234285Sdim * @param m The shared memory structure to create. 161234285Sdim * @param filename The file used to create the original segment. 162234285Sdim * (This MUST match the original filename.) 163234285Sdim * @param pool the pool from which to allocate the shared memory 164234285Sdim * structure for this process. 165234285Sdim * @param flags mask of APR_SHM_* (defined above) 166234285Sdim */ 167234285SdimAPR_DECLARE(apr_status_t) apr_shm_attach_ex(apr_shm_t **m, 168234285Sdim const char *filename, 169234285Sdim apr_pool_t *pool, 170234285Sdim apr_int32_t flags); 171234285Sdim 172234285Sdim/** 173234285Sdim * Detach from a shared memory segment without destroying it. 174234285Sdim * @param m The shared memory structure representing the segment 175234285Sdim * to detach from. 176234285Sdim */ 177234285SdimAPR_DECLARE(apr_status_t) apr_shm_detach(apr_shm_t *m); 178234285Sdim 179234285Sdim/** 180234285Sdim * Retrieve the base address of the shared memory segment. 181 * NOTE: This address is only usable within the callers address 182 * space, since this API does not guarantee that other attaching 183 * processes will maintain the same address mapping. 184 * @param m The shared memory segment from which to retrieve 185 * the base address. 186 * @return address, aligned by APR_ALIGN_DEFAULT. 187 */ 188APR_DECLARE(void *) apr_shm_baseaddr_get(const apr_shm_t *m); 189 190/** 191 * Retrieve the length of a shared memory segment in bytes. 192 * @param m The shared memory segment from which to retrieve 193 * the segment length. 194 */ 195APR_DECLARE(apr_size_t) apr_shm_size_get(const apr_shm_t *m); 196 197/** 198 * Get the pool used by this shared memory segment. 199 */ 200APR_POOL_DECLARE_ACCESSOR(shm); 201 202/** @} */ 203 204#ifdef __cplusplus 205} 206#endif 207 208#endif /* APR_SHM_T */ 209