Apache Portable Runtime
|
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more 00002 * contributor license agreements. See the NOTICE file distributed with 00003 * this work for additional information regarding copyright ownership. 00004 * The ASF licenses this file to You under the Apache License, Version 2.0 00005 * (the "License"); you may not use this file except in compliance with 00006 * the License. You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef APR_SHM_H 00018 #define APR_SHM_H 00019 00020 /** 00021 * @file apr_shm.h 00022 * @brief APR Shared Memory Routines 00023 */ 00024 00025 #include "apr.h" 00026 #include "apr_pools.h" 00027 #include "apr_errno.h" 00028 #include "apr_perms_set.h" 00029 00030 #ifdef __cplusplus 00031 extern "C" { 00032 #endif /* __cplusplus */ 00033 00034 /** 00035 * @defgroup apr_shm Shared Memory Routines 00036 * @ingroup APR 00037 * @{ 00038 */ 00039 00040 /** 00041 * Private, platform-specific data struture representing a shared memory 00042 * segment. 00043 */ 00044 typedef struct apr_shm_t apr_shm_t; 00045 00046 /** 00047 * Create and make accessible a shared memory segment with default 00048 * properties. 00049 * @param m The shared memory structure to create. 00050 * @param reqsize The desired size of the segment. 00051 * @param filename The file to use for shared memory on platforms that 00052 * require it. 00053 * @param pool the pool from which to allocate the shared memory 00054 * structure. 00055 * @remark A note about Anonymous vs. Named shared memory segments: 00056 * Not all plaforms support anonymous shared memory segments, but in 00057 * some cases it is prefered over other types of shared memory 00058 * implementations. Passing a NULL 'file' parameter to this function 00059 * will cause the subsystem to use anonymous shared memory segments. 00060 * If such a system is not available, APR_ENOTIMPL is returned. 00061 * @remark A note about allocation sizes: 00062 * On some platforms it is necessary to store some metainformation 00063 * about the segment within the actual segment. In order to supply 00064 * the caller with the requested size it may be necessary for the 00065 * implementation to request a slightly greater segment length 00066 * from the subsystem. In all cases, the apr_shm_baseaddr_get() 00067 * function will return the first usable byte of memory. 00068 * 00069 */ 00070 APR_DECLARE(apr_status_t) apr_shm_create(apr_shm_t **m, 00071 apr_size_t reqsize, 00072 const char *filename, 00073 apr_pool_t *pool); 00074 00075 /** 00076 * Special processing flags for apr_shm_create_ex() and apr_shm_attach_ex(). 00077 */ 00078 #define APR_SHM_NS_LOCAL 1 /* Create or attach to named shared memory 00079 * segment in the "Local" namespace on 00080 * Windows. (Ignored on other platforms.) 00081 * By default, the "Global" namespace is 00082 * used for privileged processes and the 00083 * "Local" namespace is used otherwise. 00084 */ 00085 #define APR_SHM_NS_GLOBAL 2 /* Create or attach to named shared memory 00086 * segment in the "Global" namespace on 00087 * Windows. (Ignored on other platforms.) 00088 */ 00089 00090 /** 00091 * Create and make accessible a shared memory segment with platform- 00092 * specific processing. 00093 * @param m The shared memory structure to create. 00094 * @param reqsize The desired size of the segment. 00095 * @param filename The file to use for shared memory on platforms that 00096 * require it. 00097 * @param pool the pool from which to allocate the shared memory 00098 * structure. 00099 * @param flags mask of APR_SHM_* (defined above) 00100 * @remark A note about Anonymous vs. Named shared memory segments: 00101 * Not all plaforms support anonymous shared memory segments, but in 00102 * some cases it is prefered over other types of shared memory 00103 * implementations. Passing a NULL 'file' parameter to this function 00104 * will cause the subsystem to use anonymous shared memory segments. 00105 * If such a system is not available, APR_ENOTIMPL is returned. 00106 * @remark A note about allocation sizes: 00107 * On some platforms it is necessary to store some metainformation 00108 * about the segment within the actual segment. In order to supply 00109 * the caller with the requested size it may be necessary for the 00110 * implementation to request a slightly greater segment length 00111 * from the subsystem. In all cases, the apr_shm_baseaddr_get() 00112 * function will return the first usable byte of memory. 00113 * 00114 */ 00115 APR_DECLARE(apr_status_t) apr_shm_create_ex(apr_shm_t **m, 00116 apr_size_t reqsize, 00117 const char *filename, 00118 apr_pool_t *pool, 00119 apr_int32_t flags); 00120 00121 /** 00122 * Remove named resource associated with a shared memory segment, 00123 * preventing attachments to the resource, but not destroying it. 00124 * @param filename The filename associated with shared-memory segment which 00125 * needs to be removed 00126 * @param pool The pool used for file operations 00127 * @remark This function is only supported on platforms which support 00128 * name-based shared memory segments, and will return APR_ENOTIMPL on 00129 * platforms without such support. Removing the file while the shm 00130 * is in use is not entirely portable, caller may use this to enhance 00131 * obscurity of the resource, but be prepared for the call to fail, 00132 * and for concurrent attempts to create a resource of the same name 00133 * to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) 00134 * also removes the named resource. 00135 */ 00136 APR_DECLARE(apr_status_t) apr_shm_remove(const char *filename, 00137 apr_pool_t *pool); 00138 00139 /** 00140 * Delete named resource associated with a shared memory segment, 00141 * preventing attachments to the resource. 00142 * @param m The shared memory segment structure to delete. 00143 * @remark This function is only supported on platforms which support 00144 * name-based shared memory segments, and will return APR_ENOTIMPL on 00145 * platforms without such support. Removing the file while the shm 00146 * is in use is not entirely portable, caller may use this to enhance 00147 * obscurity of the resource, but be prepared for the call to fail, 00148 * and for concurrent attempts to create a resource of the same name 00149 * to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) 00150 * also removes the named resource. 00151 */ 00152 APR_DECLARE(apr_status_t) apr_shm_delete(apr_shm_t *m); 00153 00154 /** 00155 * Destroy a shared memory segment and associated memory. 00156 * @param m The shared memory segment structure to destroy. 00157 */ 00158 APR_DECLARE(apr_status_t) apr_shm_destroy(apr_shm_t *m); 00159 00160 /** 00161 * Attach to a shared memory segment that was created 00162 * by another process. 00163 * @param m The shared memory structure to create. 00164 * @param filename The file used to create the original segment. 00165 * (This MUST match the original filename.) 00166 * @param pool the pool from which to allocate the shared memory 00167 * structure for this process. 00168 */ 00169 APR_DECLARE(apr_status_t) apr_shm_attach(apr_shm_t **m, 00170 const char *filename, 00171 apr_pool_t *pool); 00172 00173 /** 00174 * Attach to a shared memory segment that was created 00175 * by another process, with platform-specific processing. 00176 * @param m The shared memory structure to create. 00177 * @param filename The file used to create the original segment. 00178 * (This MUST match the original filename.) 00179 * @param pool the pool from which to allocate the shared memory 00180 * structure for this process. 00181 * @param flags mask of APR_SHM_* (defined above) 00182 */ 00183 APR_DECLARE(apr_status_t) apr_shm_attach_ex(apr_shm_t **m, 00184 const char *filename, 00185 apr_pool_t *pool, 00186 apr_int32_t flags); 00187 00188 /** 00189 * Detach from a shared memory segment without destroying it. 00190 * @param m The shared memory structure representing the segment 00191 * to detach from. 00192 */ 00193 APR_DECLARE(apr_status_t) apr_shm_detach(apr_shm_t *m); 00194 00195 /** 00196 * Retrieve the base address of the shared memory segment. 00197 * NOTE: This address is only usable within the callers address 00198 * space, since this API does not guarantee that other attaching 00199 * processes will maintain the same address mapping. 00200 * @param m The shared memory segment from which to retrieve 00201 * the base address. 00202 * @return address, aligned by APR_ALIGN_DEFAULT. 00203 */ 00204 APR_DECLARE(void *) apr_shm_baseaddr_get(const apr_shm_t *m); 00205 00206 /** 00207 * Retrieve the length of a shared memory segment in bytes. 00208 * @param m The shared memory segment from which to retrieve 00209 * the segment length. 00210 */ 00211 APR_DECLARE(apr_size_t) apr_shm_size_get(const apr_shm_t *m); 00212 00213 /** 00214 * Set shared memory permissions. 00215 */ 00216 APR_PERMS_SET_IMPLEMENT(shm); 00217 00218 /** 00219 * Get the pool used by this shared memory segment. 00220 */ 00221 APR_POOL_DECLARE_ACCESSOR(shm); 00222 00223 /** @} */ 00224 00225 #ifdef __cplusplus 00226 } 00227 #endif 00228 00229 #endif /* APR_SHM_T */