apr_shm.h revision 251875
1127664Sbms/* Licensed to the Apache Software Foundation (ASF) under one or more 2127664Sbms * contributor license agreements. See the NOTICE file distributed with 3127664Sbms * this work for additional information regarding copyright ownership. 4127664Sbms * The ASF licenses this file to You under the Apache License, Version 2.0 5127664Sbms * (the "License"); you may not use this file except in compliance with 6127664Sbms * the License. You may obtain a copy of the License at 7127664Sbms * 8127664Sbms * http://www.apache.org/licenses/LICENSE-2.0 9127664Sbms * 10127664Sbms * Unless required by applicable law or agreed to in writing, software 11127664Sbms * distributed under the License is distributed on an "AS IS" BASIS, 12127664Sbms * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13127664Sbms * See the License for the specific language governing permissions and 14127664Sbms * limitations under the License. 15127664Sbms */ 16127664Sbms 17127664Sbms#ifndef APR_SHM_H 18127664Sbms#define APR_SHM_H 19127664Sbms 20127664Sbms/** 21127664Sbms * @file apr_shm.h 22127664Sbms * @brief APR Shared Memory Routines 23127664Sbms */ 24127664Sbms 25127664Sbms#include "apr.h" 26127664Sbms#include "apr_pools.h" 27127664Sbms#include "apr_errno.h" 28127664Sbms 29127664Sbms#ifdef __cplusplus 30127664Sbmsextern "C" { 31127664Sbms#endif /* __cplusplus */ 32127664Sbms 33127664Sbms/** 34127664Sbms * @defgroup apr_shm Shared Memory Routines 35127664Sbms * @ingroup APR 36127664Sbms * @{ 37127664Sbms */ 38127664Sbms 39127664Sbms/** 40127664Sbms * Private, platform-specific data struture representing a shared memory 41127664Sbms * segment. 42127664Sbms */ 43127664Sbmstypedef struct apr_shm_t apr_shm_t; 44127664Sbms 45127664Sbms/** 46 * Create and make accessable a shared memory segment. 47 * @param m The shared memory structure to create. 48 * @param reqsize The desired size of the segment. 49 * @param filename The file to use for shared memory on platforms that 50 * require it. 51 * @param pool the pool from which to allocate the shared memory 52 * structure. 53 * @remark A note about Anonymous vs. Named shared memory segments: 54 * Not all plaforms support anonymous shared memory segments, but in 55 * some cases it is prefered over other types of shared memory 56 * implementations. Passing a NULL 'file' parameter to this function 57 * will cause the subsystem to use anonymous shared memory segments. 58 * If such a system is not available, APR_ENOTIMPL is returned. 59 * @remark A note about allocation sizes: 60 * On some platforms it is necessary to store some metainformation 61 * about the segment within the actual segment. In order to supply 62 * the caller with the requested size it may be necessary for the 63 * implementation to request a slightly greater segment length 64 * from the subsystem. In all cases, the apr_shm_baseaddr_get() 65 * function will return the first usable byte of memory. 66 * 67 */ 68APR_DECLARE(apr_status_t) apr_shm_create(apr_shm_t **m, 69 apr_size_t reqsize, 70 const char *filename, 71 apr_pool_t *pool); 72 73/** 74 * Remove named resource associated with a shared memory segment, 75 * preventing attachments to the resource, but not destroying it. 76 * @param filename The filename associated with shared-memory segment which 77 * needs to be removed 78 * @param pool The pool used for file operations 79 * @remark This function is only supported on platforms which support 80 * name-based shared memory segments, and will return APR_ENOTIMPL on 81 * platforms without such support. Removing the file while the shm 82 * is in use is not entirely portable, caller may use this to enhance 83 * obscurity of the resource, but be prepared for the the call to fail, 84 * and for concurrent attempts to create a resource of the same name 85 * to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) 86 * also removes the named resource. 87 */ 88APR_DECLARE(apr_status_t) apr_shm_remove(const char *filename, 89 apr_pool_t *pool); 90 91/** 92 * Destroy a shared memory segment and associated memory. 93 * @param m The shared memory segment structure to destroy. 94 */ 95APR_DECLARE(apr_status_t) apr_shm_destroy(apr_shm_t *m); 96 97/** 98 * Attach to a shared memory segment that was created 99 * by another process. 100 * @param m The shared memory structure to create. 101 * @param filename The file used to create the original segment. 102 * (This MUST match the original filename.) 103 * @param pool the pool from which to allocate the shared memory 104 * structure for this process. 105 */ 106APR_DECLARE(apr_status_t) apr_shm_attach(apr_shm_t **m, 107 const char *filename, 108 apr_pool_t *pool); 109 110/** 111 * Detach from a shared memory segment without destroying it. 112 * @param m The shared memory structure representing the segment 113 * to detach from. 114 */ 115APR_DECLARE(apr_status_t) apr_shm_detach(apr_shm_t *m); 116 117/** 118 * Retrieve the base address of the shared memory segment. 119 * NOTE: This address is only usable within the callers address 120 * space, since this API does not guarantee that other attaching 121 * processes will maintain the same address mapping. 122 * @param m The shared memory segment from which to retrieve 123 * the base address. 124 * @return address, aligned by APR_ALIGN_DEFAULT. 125 */ 126APR_DECLARE(void *) apr_shm_baseaddr_get(const apr_shm_t *m); 127 128/** 129 * Retrieve the length of a shared memory segment in bytes. 130 * @param m The shared memory segment from which to retrieve 131 * the segment length. 132 */ 133APR_DECLARE(apr_size_t) apr_shm_size_get(const apr_shm_t *m); 134 135/** 136 * Get the pool used by this shared memory segment. 137 */ 138APR_POOL_DECLARE_ACCESSOR(shm); 139 140/** @} */ 141 142#ifdef __cplusplus 143} 144#endif 145 146#endif /* APR_SHM_T */ 147