1251875Speter/* Licensed to the Apache Software Foundation (ASF) under one or more 2251875Speter * contributor license agreements. See the NOTICE file distributed with 3251875Speter * this work for additional information regarding copyright ownership. 4251875Speter * The ASF licenses this file to You under the Apache License, Version 2.0 5251875Speter * (the "License"); you may not use this file except in compliance with 6251875Speter * the License. You may obtain a copy of the License at 7251875Speter * 8251875Speter * http://www.apache.org/licenses/LICENSE-2.0 9251875Speter * 10251875Speter * Unless required by applicable law or agreed to in writing, software 11251875Speter * distributed under the License is distributed on an "AS IS" BASIS, 12251875Speter * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13251875Speter * See the License for the specific language governing permissions and 14251875Speter * limitations under the License. 15251875Speter */ 16251875Speter 17251875Speter#ifndef APR_SHM_H 18251875Speter#define APR_SHM_H 19251875Speter 20251875Speter/** 21251875Speter * @file apr_shm.h 22251875Speter * @brief APR Shared Memory Routines 23251875Speter */ 24251875Speter 25251875Speter#include "apr.h" 26251875Speter#include "apr_pools.h" 27251875Speter#include "apr_errno.h" 28362181Sdim#include "apr_perms_set.h" 29251875Speter 30251875Speter#ifdef __cplusplus 31251875Speterextern "C" { 32251875Speter#endif /* __cplusplus */ 33251875Speter 34251875Speter/** 35251875Speter * @defgroup apr_shm Shared Memory Routines 36251875Speter * @ingroup APR 37251875Speter * @{ 38251875Speter */ 39251875Speter 40251875Speter/** 41251875Speter * Private, platform-specific data struture representing a shared memory 42251875Speter * segment. 43251875Speter */ 44251875Spetertypedef struct apr_shm_t apr_shm_t; 45251875Speter 46251875Speter/** 47266735Speter * Create and make accessible a shared memory segment with default 48266735Speter * properties. 49251875Speter * @param m The shared memory structure to create. 50251875Speter * @param reqsize The desired size of the segment. 51251875Speter * @param filename The file to use for shared memory on platforms that 52251875Speter * require it. 53251875Speter * @param pool the pool from which to allocate the shared memory 54251875Speter * structure. 55251875Speter * @remark A note about Anonymous vs. Named shared memory segments: 56251875Speter * Not all plaforms support anonymous shared memory segments, but in 57251875Speter * some cases it is prefered over other types of shared memory 58251875Speter * implementations. Passing a NULL 'file' parameter to this function 59251875Speter * will cause the subsystem to use anonymous shared memory segments. 60251875Speter * If such a system is not available, APR_ENOTIMPL is returned. 61251875Speter * @remark A note about allocation sizes: 62251875Speter * On some platforms it is necessary to store some metainformation 63251875Speter * about the segment within the actual segment. In order to supply 64251875Speter * the caller with the requested size it may be necessary for the 65251875Speter * implementation to request a slightly greater segment length 66251875Speter * from the subsystem. In all cases, the apr_shm_baseaddr_get() 67251875Speter * function will return the first usable byte of memory. 68251875Speter * 69251875Speter */ 70251875SpeterAPR_DECLARE(apr_status_t) apr_shm_create(apr_shm_t **m, 71251875Speter apr_size_t reqsize, 72251875Speter const char *filename, 73251875Speter apr_pool_t *pool); 74251875Speter 75251875Speter/** 76266735Speter * Special processing flags for apr_shm_create_ex() and apr_shm_attach_ex(). 77266735Speter */ 78266735Speter#define APR_SHM_NS_LOCAL 1 /* Create or attach to named shared memory 79266735Speter * segment in the "Local" namespace on 80266735Speter * Windows. (Ignored on other platforms.) 81266735Speter * By default, the "Global" namespace is 82266735Speter * used for privileged processes and the 83266735Speter * "Local" namespace is used otherwise. 84266735Speter */ 85266735Speter#define APR_SHM_NS_GLOBAL 2 /* Create or attach to named shared memory 86266735Speter * segment in the "Global" namespace on 87266735Speter * Windows. (Ignored on other platforms.) 88266735Speter */ 89266735Speter 90266735Speter/** 91266735Speter * Create and make accessible a shared memory segment with platform- 92266735Speter * specific processing. 93266735Speter * @param m The shared memory structure to create. 94266735Speter * @param reqsize The desired size of the segment. 95266735Speter * @param filename The file to use for shared memory on platforms that 96266735Speter * require it. 97266735Speter * @param pool the pool from which to allocate the shared memory 98266735Speter * structure. 99266735Speter * @param flags mask of APR_SHM_* (defined above) 100266735Speter * @remark A note about Anonymous vs. Named shared memory segments: 101266735Speter * Not all plaforms support anonymous shared memory segments, but in 102266735Speter * some cases it is prefered over other types of shared memory 103266735Speter * implementations. Passing a NULL 'file' parameter to this function 104266735Speter * will cause the subsystem to use anonymous shared memory segments. 105266735Speter * If such a system is not available, APR_ENOTIMPL is returned. 106266735Speter * @remark A note about allocation sizes: 107266735Speter * On some platforms it is necessary to store some metainformation 108266735Speter * about the segment within the actual segment. In order to supply 109266735Speter * the caller with the requested size it may be necessary for the 110266735Speter * implementation to request a slightly greater segment length 111266735Speter * from the subsystem. In all cases, the apr_shm_baseaddr_get() 112266735Speter * function will return the first usable byte of memory. 113266735Speter * 114266735Speter */ 115266735SpeterAPR_DECLARE(apr_status_t) apr_shm_create_ex(apr_shm_t **m, 116266735Speter apr_size_t reqsize, 117266735Speter const char *filename, 118266735Speter apr_pool_t *pool, 119266735Speter apr_int32_t flags); 120266735Speter 121266735Speter/** 122251875Speter * Remove named resource associated with a shared memory segment, 123251875Speter * preventing attachments to the resource, but not destroying it. 124251875Speter * @param filename The filename associated with shared-memory segment which 125251875Speter * needs to be removed 126251875Speter * @param pool The pool used for file operations 127251875Speter * @remark This function is only supported on platforms which support 128251875Speter * name-based shared memory segments, and will return APR_ENOTIMPL on 129251875Speter * platforms without such support. Removing the file while the shm 130251875Speter * is in use is not entirely portable, caller may use this to enhance 131266735Speter * obscurity of the resource, but be prepared for the call to fail, 132251875Speter * and for concurrent attempts to create a resource of the same name 133251875Speter * to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) 134251875Speter * also removes the named resource. 135251875Speter */ 136251875SpeterAPR_DECLARE(apr_status_t) apr_shm_remove(const char *filename, 137251875Speter apr_pool_t *pool); 138251875Speter 139251875Speter/** 140362181Sdim * Delete named resource associated with a shared memory segment, 141362181Sdim * preventing attachments to the resource. 142362181Sdim * @param m The shared memory segment structure to delete. 143362181Sdim * @remark This function is only supported on platforms which support 144362181Sdim * name-based shared memory segments, and will return APR_ENOTIMPL on 145362181Sdim * platforms without such support. Removing the file while the shm 146362181Sdim * is in use is not entirely portable, caller may use this to enhance 147362181Sdim * obscurity of the resource, but be prepared for the call to fail, 148362181Sdim * and for concurrent attempts to create a resource of the same name 149362181Sdim * to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) 150362181Sdim * also removes the named resource. 151362181Sdim */ 152362181SdimAPR_DECLARE(apr_status_t) apr_shm_delete(apr_shm_t *m); 153362181Sdim 154362181Sdim/** 155251875Speter * Destroy a shared memory segment and associated memory. 156251875Speter * @param m The shared memory segment structure to destroy. 157251875Speter */ 158251875SpeterAPR_DECLARE(apr_status_t) apr_shm_destroy(apr_shm_t *m); 159251875Speter 160251875Speter/** 161251875Speter * Attach to a shared memory segment that was created 162251875Speter * by another process. 163251875Speter * @param m The shared memory structure to create. 164251875Speter * @param filename The file used to create the original segment. 165251875Speter * (This MUST match the original filename.) 166251875Speter * @param pool the pool from which to allocate the shared memory 167251875Speter * structure for this process. 168251875Speter */ 169251875SpeterAPR_DECLARE(apr_status_t) apr_shm_attach(apr_shm_t **m, 170251875Speter const char *filename, 171251875Speter apr_pool_t *pool); 172251875Speter 173251875Speter/** 174266735Speter * Attach to a shared memory segment that was created 175266735Speter * by another process, with platform-specific processing. 176266735Speter * @param m The shared memory structure to create. 177266735Speter * @param filename The file used to create the original segment. 178266735Speter * (This MUST match the original filename.) 179266735Speter * @param pool the pool from which to allocate the shared memory 180266735Speter * structure for this process. 181266735Speter * @param flags mask of APR_SHM_* (defined above) 182266735Speter */ 183266735SpeterAPR_DECLARE(apr_status_t) apr_shm_attach_ex(apr_shm_t **m, 184266735Speter const char *filename, 185266735Speter apr_pool_t *pool, 186266735Speter apr_int32_t flags); 187266735Speter 188266735Speter/** 189251875Speter * Detach from a shared memory segment without destroying it. 190251875Speter * @param m The shared memory structure representing the segment 191251875Speter * to detach from. 192251875Speter */ 193251875SpeterAPR_DECLARE(apr_status_t) apr_shm_detach(apr_shm_t *m); 194251875Speter 195251875Speter/** 196251875Speter * Retrieve the base address of the shared memory segment. 197251875Speter * NOTE: This address is only usable within the callers address 198251875Speter * space, since this API does not guarantee that other attaching 199251875Speter * processes will maintain the same address mapping. 200251875Speter * @param m The shared memory segment from which to retrieve 201251875Speter * the base address. 202251875Speter * @return address, aligned by APR_ALIGN_DEFAULT. 203251875Speter */ 204251875SpeterAPR_DECLARE(void *) apr_shm_baseaddr_get(const apr_shm_t *m); 205251875Speter 206251875Speter/** 207251875Speter * Retrieve the length of a shared memory segment in bytes. 208251875Speter * @param m The shared memory segment from which to retrieve 209251875Speter * the segment length. 210251875Speter */ 211251875SpeterAPR_DECLARE(apr_size_t) apr_shm_size_get(const apr_shm_t *m); 212251875Speter 213251875Speter/** 214362181Sdim * Set shared memory permissions. 215362181Sdim */ 216362181SdimAPR_PERMS_SET_IMPLEMENT(shm); 217362181Sdim 218362181Sdim/** 219251875Speter * Get the pool used by this shared memory segment. 220251875Speter */ 221251875SpeterAPR_POOL_DECLARE_ACCESSOR(shm); 222251875Speter 223251875Speter/** @} */ 224251875Speter 225251875Speter#ifdef __cplusplus 226251875Speter} 227251875Speter#endif 228251875Speter 229251875Speter#endif /* APR_SHM_T */ 230