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/* This header file is where you should put ANY platform specific information. 18 * This should be the only header file that programs need to include that 19 * actually has platform dependent code which refers to the . 20 */ 21#ifndef APR_PORTABLE_H 22#define APR_PORTABLE_H 23/** 24 * @file apr_portable.h 25 * @brief APR Portability Routines 26 */ 27 28#include "apr.h" 29#include "apr_pools.h" 30#include "apr_thread_proc.h" 31#include "apr_file_io.h" 32#include "apr_network_io.h" 33#include "apr_errno.h" 34#include "apr_global_mutex.h" 35#include "apr_proc_mutex.h" 36#include "apr_time.h" 37#include "apr_dso.h" 38#include "apr_shm.h" 39 40#if APR_HAVE_DIRENT_H 41#include <dirent.h> 42#endif 43#if APR_HAVE_FCNTL_H 44#include <fcntl.h> 45#endif 46#if APR_HAVE_PTHREAD_H 47#include <pthread.h> 48#endif 49#if APR_HAVE_SEMAPHORE_H 50#include <semaphore.h> 51#endif 52 53#ifdef __cplusplus 54extern "C" { 55#endif /* __cplusplus */ 56 57/** 58 * @defgroup apr_portabile Portability Routines 59 * @ingroup APR 60 * @{ 61 */ 62 63#ifdef WIN32 64/* The primitives for Windows types */ 65typedef HANDLE apr_os_file_t; 66typedef HANDLE apr_os_dir_t; 67typedef SOCKET apr_os_sock_t; 68typedef HANDLE apr_os_proc_mutex_t; 69typedef HANDLE apr_os_thread_t; 70typedef HANDLE apr_os_proc_t; 71typedef DWORD apr_os_threadkey_t; 72typedef FILETIME apr_os_imp_time_t; 73typedef SYSTEMTIME apr_os_exp_time_t; 74typedef HANDLE apr_os_dso_handle_t; 75typedef HANDLE apr_os_shm_t; 76 77#elif defined(OS2) 78typedef HFILE apr_os_file_t; 79typedef HDIR apr_os_dir_t; 80typedef int apr_os_sock_t; 81typedef HMTX apr_os_proc_mutex_t; 82typedef TID apr_os_thread_t; 83typedef PID apr_os_proc_t; 84typedef PULONG apr_os_threadkey_t; 85typedef struct timeval apr_os_imp_time_t; 86typedef struct tm apr_os_exp_time_t; 87typedef HMODULE apr_os_dso_handle_t; 88typedef void* apr_os_shm_t; 89 90#elif defined(__BEOS__) 91#include <kernel/OS.h> 92#include <kernel/image.h> 93 94struct apr_os_proc_mutex_t { 95 sem_id sem; 96 int32 ben; 97}; 98 99typedef int apr_os_file_t; 100typedef DIR apr_os_dir_t; 101typedef int apr_os_sock_t; 102typedef struct apr_os_proc_mutex_t apr_os_proc_mutex_t; 103typedef thread_id apr_os_thread_t; 104typedef thread_id apr_os_proc_t; 105typedef int apr_os_threadkey_t; 106typedef struct timeval apr_os_imp_time_t; 107typedef struct tm apr_os_exp_time_t; 108typedef image_id apr_os_dso_handle_t; 109typedef void* apr_os_shm_t; 110 111#elif defined(NETWARE) 112typedef int apr_os_file_t; 113typedef DIR apr_os_dir_t; 114typedef int apr_os_sock_t; 115typedef NXMutex_t apr_os_proc_mutex_t; 116typedef NXThreadId_t apr_os_thread_t; 117typedef long apr_os_proc_t; 118typedef NXKey_t apr_os_threadkey_t; 119typedef struct timeval apr_os_imp_time_t; 120typedef struct tm apr_os_exp_time_t; 121typedef void * apr_os_dso_handle_t; 122typedef void* apr_os_shm_t; 123 124#else 125/* Any other OS should go above this one. This is the lowest common 126 * denominator typedefs for all UNIX-like systems. :) 127 */ 128 129/** Basic OS process mutex structure. */ 130struct apr_os_proc_mutex_t { 131#if APR_HAS_SYSVSEM_SERIALIZE || APR_HAS_FCNTL_SERIALIZE || APR_HAS_FLOCK_SERIALIZE 132 /** Value used for SYS V Semaphore, FCNTL and FLOCK serialization */ 133 int crossproc; 134#endif 135#if APR_HAS_PROC_PTHREAD_SERIALIZE 136 /** Value used for PTHREAD serialization */ 137 pthread_mutex_t *pthread_interproc; 138#endif 139#if APR_HAS_THREADS 140 /* If no threads, no need for thread locks */ 141#if APR_USE_PTHREAD_SERIALIZE 142 /** This value is currently unused within APR and Apache */ 143 pthread_mutex_t *intraproc; 144#endif 145#endif 146#if APR_HAS_POSIXSEM_SERIALIZE 147 /** Value used for POSIX semaphores serialization */ 148 sem_t *psem_interproc; 149#endif 150}; 151 152typedef int apr_os_file_t; /**< native file */ 153typedef DIR apr_os_dir_t; /**< native dir */ 154typedef int apr_os_sock_t; /**< native dir */ 155typedef struct apr_os_proc_mutex_t apr_os_proc_mutex_t; /**< native process 156 * mutex 157 */ 158#if APR_HAS_THREADS && APR_HAVE_PTHREAD_H 159typedef pthread_t apr_os_thread_t; /**< native thread */ 160typedef pthread_key_t apr_os_threadkey_t; /**< native thread address 161 * space */ 162#endif 163typedef pid_t apr_os_proc_t; /**< native pid */ 164typedef struct timeval apr_os_imp_time_t; /**< native timeval */ 165typedef struct tm apr_os_exp_time_t; /**< native tm */ 166/** @var apr_os_dso_handle_t 167 * native dso types 168 */ 169#if defined(HPUX) || defined(HPUX10) || defined(HPUX11) 170#include <dl.h> 171typedef shl_t apr_os_dso_handle_t; 172#elif defined(DARWIN) 173#include <mach-o/dyld.h> 174typedef NSModule apr_os_dso_handle_t; 175#else 176typedef void * apr_os_dso_handle_t; 177#endif 178typedef void* apr_os_shm_t; /**< native SHM */ 179 180#endif 181 182/** 183 * @typedef apr_os_sock_info_t 184 * @brief alias for local OS socket 185 */ 186/** 187 * everything APR needs to know about an active socket to construct 188 * an APR socket from it; currently, this is platform-independent 189 */ 190struct apr_os_sock_info_t { 191 apr_os_sock_t *os_sock; /**< always required */ 192 struct sockaddr *local; /**< NULL if not yet bound */ 193 struct sockaddr *remote; /**< NULL if not connected */ 194 int family; /**< always required (APR_INET, APR_INET6, etc.) */ 195 int type; /**< always required (SOCK_STREAM, SOCK_DGRAM, etc.) */ 196 int protocol; /**< 0 or actual protocol (APR_PROTO_SCTP, APR_PROTO_TCP, etc.) */ 197}; 198 199typedef struct apr_os_sock_info_t apr_os_sock_info_t; 200 201#if APR_PROC_MUTEX_IS_GLOBAL || defined(DOXYGEN) 202/** Opaque global mutex type */ 203#define apr_os_global_mutex_t apr_os_proc_mutex_t 204/** @return apr_os_global_mutex */ 205#define apr_os_global_mutex_get apr_os_proc_mutex_get 206#else 207 /** Thread and process mutex for those platforms where process mutexes 208 * are not held in threads. 209 */ 210 struct apr_os_global_mutex_t { 211 apr_pool_t *pool; 212 apr_proc_mutex_t *proc_mutex; 213#if APR_HAS_THREADS 214 apr_thread_mutex_t *thread_mutex; 215#endif /* APR_HAS_THREADS */ 216 }; 217 typedef struct apr_os_global_mutex_t apr_os_global_mutex_t; 218 219APR_DECLARE(apr_status_t) apr_os_global_mutex_get(apr_os_global_mutex_t *ospmutex, 220 apr_global_mutex_t *pmutex); 221#endif 222 223 224/** 225 * convert the file from apr type to os specific type. 226 * @param thefile The os specific file we are converting to 227 * @param file The apr file to convert. 228 * @remark On Unix, it is only possible to get a file descriptor from 229 * an apr file type. 230 */ 231APR_DECLARE(apr_status_t) apr_os_file_get(apr_os_file_t *thefile, 232 apr_file_t *file); 233 234/** 235 * convert the dir from apr type to os specific type. 236 * @param thedir The os specific dir we are converting to 237 * @param dir The apr dir to convert. 238 */ 239APR_DECLARE(apr_status_t) apr_os_dir_get(apr_os_dir_t **thedir, 240 apr_dir_t *dir); 241 242/** 243 * Convert the socket from an apr type to an OS specific socket 244 * @param thesock The socket to convert. 245 * @param sock The os specific equivalent of the apr socket.. 246 */ 247APR_DECLARE(apr_status_t) apr_os_sock_get(apr_os_sock_t *thesock, 248 apr_socket_t *sock); 249 250/** 251 * Convert the proc mutex from apr type to os specific type 252 * @param ospmutex The os specific proc mutex we are converting to. 253 * @param pmutex The apr proc mutex to convert. 254 */ 255APR_DECLARE(apr_status_t) apr_os_proc_mutex_get(apr_os_proc_mutex_t *ospmutex, 256 apr_proc_mutex_t *pmutex); 257 258/** 259 * Convert the proc mutex from apr type to os specific type, also 260 * providing the mechanism used by the apr mutex. 261 * @param ospmutex The os specific proc mutex we are converting to. 262 * @param pmutex The apr proc mutex to convert. 263 * @param mech The mechanism used by the apr proc mutex (if not NULL). 264 * @remark Allows for disambiguation for platforms with multiple mechanisms 265 * available. 266 */ 267APR_DECLARE(apr_status_t) apr_os_proc_mutex_get_ex(apr_os_proc_mutex_t *ospmutex, 268 apr_proc_mutex_t *pmutex, 269 apr_lockmech_e *mech); 270 271/** 272 * Get the exploded time in the platforms native format. 273 * @param ostime the native time format 274 * @param aprtime the time to convert 275 */ 276APR_DECLARE(apr_status_t) apr_os_exp_time_get(apr_os_exp_time_t **ostime, 277 apr_time_exp_t *aprtime); 278 279/** 280 * Get the imploded time in the platforms native format. 281 * @param ostime the native time format 282 * @param aprtime the time to convert 283 */ 284APR_DECLARE(apr_status_t) apr_os_imp_time_get(apr_os_imp_time_t **ostime, 285 apr_time_t *aprtime); 286 287/** 288 * convert the shm from apr type to os specific type. 289 * @param osshm The os specific shm representation 290 * @param shm The apr shm to convert. 291 */ 292APR_DECLARE(apr_status_t) apr_os_shm_get(apr_os_shm_t *osshm, 293 apr_shm_t *shm); 294 295#if APR_HAS_THREADS || defined(DOXYGEN) 296/** 297 * @defgroup apr_os_thread Thread portability Routines 298 * @{ 299 */ 300/** 301 * convert the thread to os specific type from apr type. 302 * @param thethd The apr thread to convert 303 * @param thd The os specific thread we are converting to 304 */ 305APR_DECLARE(apr_status_t) apr_os_thread_get(apr_os_thread_t **thethd, 306 apr_thread_t *thd); 307 308/** 309 * convert the thread private memory key to os specific type from an apr type. 310 * @param thekey The apr handle we are converting from. 311 * @param key The os specific handle we are converting to. 312 */ 313APR_DECLARE(apr_status_t) apr_os_threadkey_get(apr_os_threadkey_t *thekey, 314 apr_threadkey_t *key); 315 316/** 317 * convert the thread from os specific type to apr type. 318 * @param thd The apr thread we are converting to. 319 * @param thethd The os specific thread to convert 320 * @param cont The pool to use if it is needed. 321 */ 322APR_DECLARE(apr_status_t) apr_os_thread_put(apr_thread_t **thd, 323 apr_os_thread_t *thethd, 324 apr_pool_t *cont); 325 326/** 327 * convert the thread private memory key from os specific type to apr type. 328 * @param key The apr handle we are converting to. 329 * @param thekey The os specific handle to convert 330 * @param cont The pool to use if it is needed. 331 */ 332APR_DECLARE(apr_status_t) apr_os_threadkey_put(apr_threadkey_t **key, 333 apr_os_threadkey_t *thekey, 334 apr_pool_t *cont); 335/** 336 * Get the thread ID 337 */ 338APR_DECLARE(apr_os_thread_t) apr_os_thread_current(void); 339 340/** 341 * Compare two thread id's 342 * @param tid1 1st Thread ID to compare 343 * @param tid2 2nd Thread ID to compare 344 * @return non-zero if the two threads are equal, zero otherwise 345 */ 346APR_DECLARE(int) apr_os_thread_equal(apr_os_thread_t tid1, 347 apr_os_thread_t tid2); 348 349/** @} */ 350#endif /* APR_HAS_THREADS */ 351 352/** 353 * convert the file from os specific type to apr type. 354 * @param file The apr file we are converting to. 355 * @param thefile The os specific file to convert 356 * @param flags The flags that were used to open this file. 357 * @param cont The pool to use if it is needed. 358 * @remark On Unix, it is only possible to put a file descriptor into 359 * an apr file type. 360 */ 361APR_DECLARE(apr_status_t) apr_os_file_put(apr_file_t **file, 362 apr_os_file_t *thefile, 363 apr_int32_t flags, apr_pool_t *cont); 364 365/** 366 * convert the file from os specific type to apr type. 367 * @param file The apr file we are converting to. 368 * @param thefile The os specific pipe to convert 369 * @param cont The pool to use if it is needed. 370 * @remark On Unix, it is only possible to put a file descriptor into 371 * an apr file type. 372 */ 373APR_DECLARE(apr_status_t) apr_os_pipe_put(apr_file_t **file, 374 apr_os_file_t *thefile, 375 apr_pool_t *cont); 376 377/** 378 * convert the file from os specific type to apr type. 379 * @param file The apr file we are converting to. 380 * @param thefile The os specific pipe to convert 381 * @param register_cleanup A cleanup will be registered on the apr_file_t 382 * to issue apr_file_close(). 383 * @param cont The pool to use if it is needed. 384 * @remark On Unix, it is only possible to put a file descriptor into 385 * an apr file type. 386 */ 387APR_DECLARE(apr_status_t) apr_os_pipe_put_ex(apr_file_t **file, 388 apr_os_file_t *thefile, 389 int register_cleanup, 390 apr_pool_t *cont); 391 392/** 393 * convert the dir from os specific type to apr type. 394 * @param dir The apr dir we are converting to. 395 * @param thedir The os specific dir to convert 396 * @param cont The pool to use when creating to apr directory. 397 */ 398APR_DECLARE(apr_status_t) apr_os_dir_put(apr_dir_t **dir, 399 apr_os_dir_t *thedir, 400 apr_pool_t *cont); 401 402/** 403 * Convert a socket from the os specific type to the APR type. If 404 * sock points to NULL, a socket will be created from the pool 405 * provided. If **sock does not point to NULL, the structure pointed 406 * to by sock will be reused and updated with the given socket. 407 * @param sock The pool to use. 408 * @param thesock The socket to convert to. 409 * @param cont The socket we are converting to an apr type. 410 * @remark If it is a true socket, it is best to call apr_os_sock_make() 411 * and provide APR with more information about the socket. 412 */ 413APR_DECLARE(apr_status_t) apr_os_sock_put(apr_socket_t **sock, 414 apr_os_sock_t *thesock, 415 apr_pool_t *cont); 416 417/** 418 * Create a socket from an existing descriptor and local and remote 419 * socket addresses. 420 * @param apr_sock The new socket that has been set up 421 * @param os_sock_info The os representation of the socket handle and 422 * other characteristics of the socket 423 * @param cont The pool to use 424 * @remark If you only know the descriptor/handle or if it isn't really 425 * a true socket, use apr_os_sock_put() instead. 426 */ 427APR_DECLARE(apr_status_t) apr_os_sock_make(apr_socket_t **apr_sock, 428 apr_os_sock_info_t *os_sock_info, 429 apr_pool_t *cont); 430 431/** 432 * Convert the proc mutex from os specific type to apr type 433 * @param pmutex The apr proc mutex we are converting to. 434 * @param ospmutex The os specific proc mutex to convert. 435 * @param cont The pool to use if it is needed. 436 */ 437APR_DECLARE(apr_status_t) apr_os_proc_mutex_put(apr_proc_mutex_t **pmutex, 438 apr_os_proc_mutex_t *ospmutex, 439 apr_pool_t *cont); 440 441/** 442 * Convert the proc mutex from os specific type to apr type, using the 443 * specified mechanism. 444 * @param pmutex The apr proc mutex we are converting to. 445 * @param ospmutex The os specific proc mutex to convert. 446 * @param mech The apr mutex locking mechanism 447 * @param register_cleanup Whether to destroy the os mutex with the apr 448 * one (either on explicit destroy or pool cleanup). 449 * @param cont The pool to use if it is needed. 450 * @remark Allows for disambiguation for platforms with multiple mechanisms 451 * available. 452 */ 453APR_DECLARE(apr_status_t) apr_os_proc_mutex_put_ex(apr_proc_mutex_t **pmutex, 454 apr_os_proc_mutex_t *ospmutex, 455 apr_lockmech_e mech, 456 int register_cleanup, 457 apr_pool_t *cont); 458 459/** 460 * Put the imploded time in the APR format. 461 * @param aprtime the APR time format 462 * @param ostime the time to convert 463 * @param cont the pool to use if necessary 464 */ 465APR_DECLARE(apr_status_t) apr_os_imp_time_put(apr_time_t *aprtime, 466 apr_os_imp_time_t **ostime, 467 apr_pool_t *cont); 468 469/** 470 * Put the exploded time in the APR format. 471 * @param aprtime the APR time format 472 * @param ostime the time to convert 473 * @param cont the pool to use if necessary 474 */ 475APR_DECLARE(apr_status_t) apr_os_exp_time_put(apr_time_exp_t *aprtime, 476 apr_os_exp_time_t **ostime, 477 apr_pool_t *cont); 478 479/** 480 * convert the shared memory from os specific type to apr type. 481 * @param shm The apr shm representation of osshm 482 * @param osshm The os specific shm identity 483 * @param cont The pool to use if it is needed. 484 * @remark On fork()ed architectures, this is typically nothing more than 485 * the memory block mapped. On non-fork architectures, this is typically 486 * some internal handle to pass the mapping from process to process. 487 */ 488APR_DECLARE(apr_status_t) apr_os_shm_put(apr_shm_t **shm, 489 apr_os_shm_t *osshm, 490 apr_pool_t *cont); 491 492 493#if APR_HAS_DSO || defined(DOXYGEN) 494/** 495 * @defgroup apr_os_dso DSO (Dynamic Loading) Portability Routines 496 * @{ 497 */ 498/** 499 * convert the dso handle from os specific to apr 500 * @param dso The apr handle we are converting to 501 * @param thedso the os specific handle to convert 502 * @param pool the pool to use if it is needed 503 */ 504APR_DECLARE(apr_status_t) apr_os_dso_handle_put(apr_dso_handle_t **dso, 505 apr_os_dso_handle_t thedso, 506 apr_pool_t *pool); 507 508/** 509 * convert the apr dso handle into an os specific one 510 * @param aprdso The apr dso handle to convert 511 * @param dso The os specific dso to return 512 */ 513APR_DECLARE(apr_status_t) apr_os_dso_handle_get(apr_os_dso_handle_t *dso, 514 apr_dso_handle_t *aprdso); 515 516/** @} */ 517#endif /* APR_HAS_DSO */ 518 519 520#if APR_HAS_OS_UUID 521/** 522 * Private: apr-util's apr_uuid module when supported by the platform 523 */ 524APR_DECLARE(apr_status_t) apr_os_uuid_get(unsigned char *uuid_data); 525#endif 526 527 528/** 529 * Get the name of the system default character set. 530 * @param pool the pool to allocate the name from, if needed 531 */ 532APR_DECLARE(const char*) apr_os_default_encoding(apr_pool_t *pool); 533 534 535/** 536 * Get the name of the current locale character set. 537 * @param pool the pool to allocate the name from, if needed 538 * @remark Defers to apr_os_default_encoding() if the current locale's 539 * data can't be retrieved on this system. 540 */ 541APR_DECLARE(const char*) apr_os_locale_encoding(apr_pool_t *pool); 542 543/** @} */ 544 545#ifdef __cplusplus 546} 547#endif 548 549#endif /* ! APR_PORTABLE_H */ 550