dep/ACE_wrappers/ace/ACE.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  * @file    ACE.h
   6  *
   7  * $Id: ACE.h 82581 2008-08-11 08:58:24Z johnnyw $
   8  *
   9  * This file contains value added ACE functions that extend the
  10  * behavior of the UNIX and Win32 OS calls.
  11  *
  12  * All these ACE static functions are consolidated in a single place
  13  * in order to manage the namespace better.  These functions are put
  14  * here rather than in @c ACE_OS in order to separate concerns.
  15  *
  16  * @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
  17  */
  18 //=============================================================================
  19
  20 #ifndef ACE_ACE_H
  21 #define ACE_ACE_H
  22
  23 #include /**/ "ace/pre.h"
  24
  25 #include "ace/config-lite.h"
  26
  27 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  28 # pragma once
  29 #endif /* ACE_LACKS_PRAGMA_ONCE */
  30
  31 #include "ace/OS_NS_math.h"
  32 #include "ace/Flag_Manip.h"
  33 #include "ace/Handle_Ops.h"
  34 #include "ace/Lib_Find.h"
  35 #include "ace/Init_ACE.h"
  36 #include "ace/Sock_Connect.h"
  37 #include "ace/Default_Constants.h"
  38
  39 #if defined (ACE_EXPORT_MACRO)
  40 #  undef ACE_EXPORT_MACRO
  41 #endif
  42 #define ACE_EXPORT_MACRO ACE_Export
  43
  44 // Open versioned namespace, if enabled by the user.
  45 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  46
  47 // Forward declarations.
  48 class ACE_Time_Value;
  49 class ACE_Message_Block;
  50 class ACE_Handle_Set;
  51
  52 /**
  53  * @namespace ACE
  54  *
  55  * @brief The namespace containing the ACE framework itself.
  56  *
  57  * The ACE namespace contains all types (classes, structures,
  58  * typedefs, etc), and global functions and variables in the ACE
  59  * framework.
  60  */
  61 namespace ACE
  62 {
  63   // = ACE version information.
  64   /// e.g., the "5" in ACE 5.1.12.
  65   extern ACE_Export u_int major_version (void);
  66
  67   /// e.g., the "1" in ACE 5.1.12.
  68   extern ACE_Export u_int minor_version (void);
  69
  70   /// e.g., the "12" in ACE 5.1.12.
  71   /// Returns 0 for "stable" (non-beta) releases.
  72   extern ACE_Export u_int beta_version (void);
  73
  74   // = C++ compiler version information.
  75   /// E.g., the "SunPro C++" in SunPro C++ 4.32.0
  76   extern ACE_Export const ACE_TCHAR * compiler_name (void);
  77
  78   /// E.g., the "4" in SunPro C++ 4.32.0
  79   extern ACE_Export u_int compiler_major_version (void);
  80
  81   /// E.g., the "32" in SunPro C++ 4.32.0
  82   extern ACE_Export u_int compiler_minor_version (void);
  83
  84   /// E.g., the "0" in SunPro C++ 4.32.0
  85   extern ACE_Export u_int compiler_beta_version (void);
  86
  87   /// Check if error indicates the process being out of handles (file
  88   /// descriptors).
  89   extern ACE_Export int out_of_handles (int error);
  90
  91   /// Simple wildcard matching function supporting '*' and '?'
  92   /// return true if string s matches pattern.
  93   extern ACE_Export bool wild_match(const char* s, const char* pattern, bool case_sensitive = true);
  94
  95   /**
  96    * @name I/O operations
  97    *
  98    * Notes on common parameters:
  99    *
 100    * @a handle is the connected endpoint that will be used for I/O.
 101    *
 102    * @a buf is the buffer to write from or receive into.
 103    *
 104    * @a len is the number of bytes to transfer.
 105    *
 106    * The @a timeout parameter in the following methods indicates how
 107    * long to blocking trying to transfer data.  If @a timeout == 0,
 108    * then the call behaves as a normal send/recv call, i.e., for
 109    * blocking sockets, the call will block until action is possible;
 110    * for non-blocking sockets, @c EWOULDBLOCK will be returned if no
 111    * action is immediately possible.
 112    *
 113    * If @a timeout != 0, the call will wait until the relative time
 114    * specified in  @a *timeout elapses.
 115    *
 116    * The "_n()" I/O methods keep looping until all the data has been
 117    * transferred.  These methods also work for sockets in non-blocking
 118    * mode i.e., they keep looping on @c EWOULDBLOCK.  @a timeout is
 119    * used to make sure we keep making progress, i.e., the same timeout
 120    * value is used for every I/O operation in the loop and the timeout
 121    * is not counted down.
 122    *
 123    * The return values for the "*_n()" methods match the return values
 124    * from the non "_n()" methods and are specified as follows:
 125    *
 126    * - On complete transfer, the number of bytes transferred is returned.
 127    * - On timeout, -1 is returned, @c errno == @c ETIME.
 128    * - On error, -1 is returned, @c errno is set to appropriate error.
 129    * - On @c EOF, 0 is returned, @c errno is irrelevant.
 130    *
 131    * On partial transfers, i.e., if any data is transferred before
 132    * timeout / error / @c EOF, @a bytes_transferred> will contain the
 133    * number of bytes transferred.
 134    *
 135    * Methods with @a iovec parameter are I/O vector variants of the
 136    * I/O operations.
 137    *
 138    * Methods with the extra @a flags argument will always result in
 139    * @c send getting called. Methods without the extra @a flags
 140    * argument will result in @c send getting called on Win32
 141    * platforms, and @c write getting called on non-Win32 platforms.
 142    */
 143   //@{
 144   extern ACE_Export ssize_t recv (ACE_HANDLE handle,
 145                                   void *buf,
 146                                   size_t len,
 147                                   int flags,
 148                                   const ACE_Time_Value *timeout = 0);
 149
 150 #if defined (ACE_HAS_TLI)
 151
 152   extern ACE_Export ssize_t t_rcv (ACE_HANDLE handle,
 153                                    void *buf,
 154                                    size_t len,
 155                                    int *flags,
 156                                    const ACE_Time_Value *timeout = 0);
 157
 158 #endif /* ACE_HAS_TLI */
 159
 160   extern ACE_Export ssize_t recv (ACE_HANDLE handle,
 161                                   void *buf,
 162                                   size_t len,
 163                                   const ACE_Time_Value *timeout = 0);
 164
 165   extern ACE_Export ssize_t recvmsg (ACE_HANDLE handle,
 166                                      struct msghdr *msg,
 167                                      int flags,
 168                                      const ACE_Time_Value *timeout = 0);
 169
 170   extern ACE_Export ssize_t recvfrom (ACE_HANDLE handle,
 171                                       char *buf,
 172                                       int len,
 173                                       int flags,
 174                                       struct sockaddr *addr,
 175                                       int *addrlen,
 176                                       const ACE_Time_Value *timeout = 0);
 177
 178   ACE_NAMESPACE_INLINE_FUNCTION
 179   ssize_t recv_n (ACE_HANDLE handle,
 180                   void *buf,
 181                   size_t len,
 182                   int flags,
 183                   const ACE_Time_Value *timeout = 0,
 184                   size_t *bytes_transferred = 0);
 185
 186 #if defined (ACE_HAS_TLI)
 187
 188   ACE_NAMESPACE_INLINE_FUNCTION
 189   ssize_t t_rcv_n (ACE_HANDLE handle,
 190                    void *buf,
 191                    size_t len,
 192                    int *flags,
 193                    const ACE_Time_Value *timeout = 0,
 194                    size_t *bytes_transferred = 0);
 195
 196 #endif /* ACE_HAS_TLI */
 197
 198   ACE_NAMESPACE_INLINE_FUNCTION
 199   ssize_t recv_n (ACE_HANDLE handle,
 200                   void *buf,
 201                   size_t len,
 202                   const ACE_Time_Value *timeout = 0,
 203                   size_t *bytes_transferred = 0);
 204
 205   /// Receive into a variable number of pieces.
 206   /**
 207    * Accepts a variable, caller-specified, number of pointer/length
 208    * pairs. Arguments following @a n are char *, size_t pairs.
 209    *
 210    * @param handle The I/O handle to receive on
 211    * @param n      The total number of char *, size_t pairs following @a n.
 212    *
 213    * @return -1 on error, else total number of bytes received.
 214    */
 215   extern ACE_Export ssize_t recv (ACE_HANDLE handle, size_t n, ...);
 216
 217   extern ACE_Export ssize_t recvv (ACE_HANDLE handle,
 218                                    iovec *iov,
 219                                    int iovcnt,
 220                                    const ACE_Time_Value *timeout = 0);
 221
 222   ACE_NAMESPACE_INLINE_FUNCTION
 223   ssize_t recvv_n (ACE_HANDLE handle,
 224                    iovec *iov,
 225                    int iovcnt,
 226                    const ACE_Time_Value *timeout = 0,
 227                    size_t *bytes_transferred = 0);
 228
 229   extern ACE_Export ssize_t recv_n (ACE_HANDLE handle,
 230                                     ACE_Message_Block *message_block,
 231                                     const ACE_Time_Value *timeout = 0,
 232                                     size_t *bytes_transferred = 0);
 233
 234   extern ACE_Export ssize_t send (ACE_HANDLE handle,
 235                                   const void *buf,
 236                                   size_t len,
 237                                   int flags,
 238                                   const ACE_Time_Value *timeout = 0);
 239
 240 #if defined (ACE_HAS_TLI)
 241
 242   extern ACE_Export ssize_t t_snd (ACE_HANDLE handle,
 243                                    const void *buf,
 244                                    size_t len,
 245                                    int flags,
 246                                    const ACE_Time_Value *timeout = 0);
 247
 248 #endif /* ACE_HAS_TLI */
 249
 250   extern ACE_Export ssize_t send (ACE_HANDLE handle,
 251                                   const void *buf,
 252                                   size_t len,
 253                                   const ACE_Time_Value *timeout = 0);
 254
 255   extern ACE_Export ssize_t sendmsg (ACE_HANDLE handle,
 256                                      const struct msghdr *msg,
 257                                      int flags,
 258                                      const ACE_Time_Value *timeout = 0);
 259
 260   extern ACE_Export ssize_t sendto (ACE_HANDLE handle,
 261                                     const char *buf,
 262                                     int len,
 263                                     int flags,
 264                                     const struct sockaddr *addr,
 265                                     int addrlen,
 266                                     const ACE_Time_Value *timeout = 0);
 267
 268   ACE_NAMESPACE_INLINE_FUNCTION
 269   ssize_t send_n (ACE_HANDLE handle,
 270                   const void *buf,
 271                   size_t len,
 272                   int flags,
 273                   const ACE_Time_Value *timeout = 0,
 274                   size_t *bytes_transferred = 0);
 275
 276 #if defined (ACE_HAS_TLI)
 277
 278   ACE_NAMESPACE_INLINE_FUNCTION
 279   ssize_t t_snd_n (ACE_HANDLE handle,
 280                    const void *buf,
 281                    size_t len,
 282                    int flags,
 283                    const ACE_Time_Value *timeout = 0,
 284                    size_t *bytes_transferred = 0);
 285
 286 #endif /* ACE_HAS_TLI */
 287
 288   ACE_NAMESPACE_INLINE_FUNCTION
 289   ssize_t send_n (ACE_HANDLE handle,
 290                   const void *buf,
 291                   size_t len,
 292                   const ACE_Time_Value *timeout = 0,
 293                   size_t *bytes_transferred = 0);
 294
 295   /// Varargs variant.
 296   extern ACE_Export ssize_t send (ACE_HANDLE handle, size_t n, ...);
 297
 298   extern ACE_Export ssize_t sendv (ACE_HANDLE handle,
 299                                    const iovec *iov,
 300                                    int iovcnt,
 301                                    const ACE_Time_Value *timeout = 0);
 302
 303   ACE_NAMESPACE_INLINE_FUNCTION
 304   ssize_t sendv_n (ACE_HANDLE handle,
 305                    const iovec *iov,
 306                    int iovcnt,
 307                    const ACE_Time_Value *timeout = 0,
 308                    size_t *bytes_transferred = 0);
 309
 310   /// Send all the @a message_blocks chained through their @c next and
 311   /// @c cont pointers.  This call uses the underlying OS gather-write
 312   /// operation to reduce the domain-crossing penalty.
 313   extern ACE_Export ssize_t send_n (ACE_HANDLE handle,
 314                                     const ACE_Message_Block *message_block,
 315                                     const ACE_Time_Value *timeout = 0,
 316                                     size_t *bytes_transferred = 0);
 317
 318   // = File system I/O functions (these don't support timeouts).
 319
 320   ACE_NAMESPACE_INLINE_FUNCTION
 321   ssize_t read_n (ACE_HANDLE handle,
 322                   void *buf,
 323                   size_t len,
 324                   size_t *bytes_transferred = 0);
 325
 326   ACE_NAMESPACE_INLINE_FUNCTION
 327   ssize_t write_n (ACE_HANDLE handle,
 328                    const void *buf,
 329                    size_t len,
 330                    size_t *bytes_transferred = 0);
 331
 332   /// Write all the @a message_blocks chained through their @c next
 333   /// and @c cont pointers.  This call uses the underlying OS
 334   /// gather-write operation to reduce the domain-crossing penalty.
 335   extern ACE_Export ssize_t write_n (ACE_HANDLE handle,
 336                                      const ACE_Message_Block *message_block,
 337                                      size_t *bytes_transferred = 0);
 338
 339   extern ACE_Export ssize_t readv_n (ACE_HANDLE handle,
 340                                      iovec *iov,
 341                                      int iovcnt,
 342                                      size_t *bytes_transferred = 0);
 343
 344   extern ACE_Export ssize_t writev_n (ACE_HANDLE handle,
 345                                       const iovec *iov,
 346                                       int iovcnt,
 347                                       size_t *bytes_transferred = 0);
 348   //@}
 349
 350   /**
 351    * Wait up to @a timeout amount of time to passively establish a
 352    * connection.  This method doesn't perform the @c accept, it just
 353    * does the timed wait.
 354    */
 355   extern ACE_Export int handle_timed_accept (ACE_HANDLE listener,
 356                                              ACE_Time_Value *timeout,
 357                                              int restart);
 358
 359   /**
 360    * Wait up to @a timeout amount of time to complete an actively
 361    * established non-blocking connection.  If @a is_tli is non-0 then
 362    * we are being called by a TLI wrapper (which behaves slightly
 363    * differently from a socket wrapper).
 364    */
 365   extern ACE_Export ACE_HANDLE handle_timed_complete (
 366     ACE_HANDLE listener,
 367     const ACE_Time_Value *timeout,
 368     int is_tli = 0);
 369
 370   /**
 371    * Reset the limit on the number of open handles.  If @a new_limit
 372    * == -1 set the limit to the maximum allowable.  Otherwise, set
 373    * the limit value to @a new_limit.  If @a increase_limit_only is
 374    * non-0 then only allow increases to the limit.
 375    */
 376   extern ACE_Export int set_handle_limit (int new_limit = -1,
 377                                           int increase_limit_only = 0);
 378
 379   /**
 380    * Returns the maximum number of open handles currently permitted in
 381    * this process.  This maximum may be extended using
 382    * @c ACE::set_handle_limit.
 383    */
 384   extern ACE_Export int max_handles (void);
 385
 386   // = String functions
 387 #if !defined (ACE_HAS_WINCE)
 388   /**
 389    * Return a dynamically allocated duplicate of @a str, substituting
 390    * the environment variable if @c str[0] @c == @c '$'.  Note that
 391    * the pointer is allocated with @c ACE_OS::malloc and must be freed
 392    * by @c ACE_OS::free.
 393    */
 394   extern ACE_Export ACE_TCHAR *strenvdup (const ACE_TCHAR *str);
 395 #endif /* ACE_HAS_WINCE */
 396
 397   /// Returns a pointer to the "end" of the string, i.e., the character
 398   /// past the '\0'.
 399   extern ACE_Export const char *strend (const char *s);
 400
 401   /// This method is just like @c strdup, except that it uses
 402   /// @c operator @c new rather than @c malloc.  If @a s is NULL
 403   /// returns NULL rather than segfaulting.
 404   extern ACE_Export char *strnew (const char *s);
 405
 406   /// Delete the memory allocated by @c strnew.
 407   ACE_NAMESPACE_INLINE_FUNCTION void strdelete (char *s);
 408
 409   /// Create a fresh new copy of @a str, up to @a n chars long.  Uses
 410   /// @c ACE_OS::malloc to allocate the new string.
 411   extern ACE_Export char *strndup (const char *str, size_t n);
 412
 413   /// Create a fresh new copy of @a str, up to @a n chars long.  Uses
 414   /// @c ACE_OS::malloc to allocate the new string.
 415   extern ACE_Export char *strnnew (const char *str, size_t n);
 416
 417 #if defined (ACE_HAS_WCHAR)
 418   extern ACE_Export const wchar_t *strend (const wchar_t *s);
 419
 420   extern ACE_Export wchar_t *strnew (const wchar_t *s);
 421
 422   ACE_NAMESPACE_INLINE_FUNCTION void strdelete (wchar_t *s);
 423
 424   extern ACE_Export wchar_t *strndup (const wchar_t *str, size_t n);
 425
 426   extern ACE_Export wchar_t *strnnew (const wchar_t *str, size_t n);
 427
 428 #endif /* ACE_HAS_WCHAR */
 429
 430   /**
 431    * On Windows, determines if a specified pathname ends with ".exe"
 432    * (not case sensitive). If on Windows and there is no ".exe" suffix,
 433    * a new ACE_TCHAR array is allocated and a copy of @c pathname with
 434    * the ".exe" suffix is copied into it. In this case, the caller is
 435    * responsible for calling delete [] on the returned pointer.
 436    *
 437    * @param pathname  The name to check for a proper suffix.
 438    *
 439    * @retval @c pathname if there is a proper suffix for Windows. This is
 440    *         always the return value for non-Windows platforms.
 441    * @retval If a suffix needs to be added, returns a pointer to new[]
 442    *         allocated memory containing the original @c pathname plus
 443    *         a ".exe" suffix. The caller is responsible for freeing the
 444    *         memory using delete [].
 445    */
 446   extern ACE_Export const ACE_TCHAR *execname (const ACE_TCHAR *pathname);
 447
 448   /**
 449    * Returns the "basename" of a @a pathname separated by @a delim.
 450    * For instance, the basename of "/tmp/foo.cpp" is "foo.cpp" when
 451    * @a delim is @a '/'.
 452    */
 453   extern ACE_Export const ACE_TCHAR *basename (const ACE_TCHAR *pathname,
 454                                                ACE_TCHAR delim =
 455                                                ACE_DIRECTORY_SEPARATOR_CHAR);
 456
 457   /**
 458    * Returns the "dirname" of a @a pathname.  For instance, the
 459    * dirname of "/tmp/foo.cpp" is "/tmp" when @a delim is @a '/'.  If
 460    * @a pathname has no @a delim ".\0" is returned.  This method does
 461    * not modify @a pathname and is not reentrant.
 462    */
 463   extern ACE_Export const ACE_TCHAR *dirname (const ACE_TCHAR *pathname,
 464                                               ACE_TCHAR delim =
 465                                               ACE_DIRECTORY_SEPARATOR_CHAR);
 466
 467   /**
 468    * Returns the current timestamp in the form
 469    * "hour:minute:second:microsecond."  The month, day, and year are
 470    * also stored in the beginning of the @a date_and_time array, which
 471    * is a user-supplied array of size @a time_len> @c ACE_TCHARs.
 472    * Returns 0 if unsuccessful, else returns pointer to beginning of the
 473    * "time" portion of @a date_and_time.  If @a
 474    * return_pointer_to_first_digit is 0 then return a pointer to the
 475    * space before the time, else return a pointer to the beginning of
 476    * the time portion.
 477    */
 478   extern ACE_Export ACE_TCHAR *timestamp (ACE_TCHAR date_and_time[],
 479                                           size_t time_len,
 480                                           bool return_pointer_to_first_digit = false);
 481
 482   /**
 483    * if @a avoid_zombies == 0 call @c ACE_OS::fork directly, else
 484    * create an orphan process that's inherited by the init process;
 485    * init cleans up when the orphan process terminates so we don't
 486    * create zombies.  Returns -1 on failure and either the child PID
 487    * on success if @a avoid_zombies == 0 or 1 on success if @a
 488    * avoid_zombies != 0 (this latter behavior is a known bug that
 489    * needs to be fixed).
 490    */
 491   extern ACE_Export pid_t fork (
 492     const ACE_TCHAR *program_name = ACE_TEXT ("<unknown>"),
 493     int avoid_zombies = 0);
 494
 495   /**
 496    * Become a daemon process using the algorithm in Richard Stevens
 497    * "Advanced Programming in the UNIX Environment."  If
 498    * @a close_all_handles is non-zero then all open file handles are
 499    * closed.
 500    */
 501   extern ACE_Export int daemonize (
 502     const ACE_TCHAR pathname[] = ACE_TEXT ("/"),
 503     bool close_all_handles = ACE_DEFAULT_CLOSE_ALL_HANDLES,
 504     const ACE_TCHAR program_name[] = ACE_TEXT ("<unknown>"));
 505
 506   // = Miscellaneous functions.
 507   /// Rounds the request to a multiple of the page size.
 508   extern ACE_Export size_t round_to_pagesize (size_t len);
 509
 510   /// Rounds the request to a multiple of the allocation granularity.
 511   extern ACE_Export size_t round_to_allocation_granularity (size_t len);
 512
 513   // @@ UNICODE what about buffer?
 514   /// Format buffer into printable format.  This is useful for
 515   /// debugging.
 516   extern ACE_Export size_t format_hexdump (const char *buffer, size_t size,
 517                                            ACE_TCHAR *obuf, size_t obuf_sz);
 518
 519   /// Computes the hash value of {str} using the "Hash PJW" routine.
 520   extern ACE_Export u_long hash_pjw (const char *str);
 521
 522   /// Computes the hash value of {str} using the "Hash PJW" routine.
 523   extern ACE_Export u_long hash_pjw (const char *str, size_t len);
 524
 525 #if defined (ACE_HAS_WCHAR)
 526   /// Computes the hash value of {str} using the "Hash PJW" routine.
 527   extern ACE_Export u_long hash_pjw (const wchar_t *str);
 528
 529   /// Computes the hash value of {str} using the "Hash PJW" routine.
 530   extern ACE_Export u_long hash_pjw (const wchar_t *str, size_t len);
 531 #endif /* ACE_HAS_WCHAR */
 532
 533   /// Computes CRC-CCITT for the string.
 534   extern ACE_Export ACE_UINT16 crc_ccitt(const char *str);
 535
 536   /// Computes CRC-CCITT for the buffer.
 537   extern ACE_Export ACE_UINT16 crc_ccitt(const void *buf, size_t len,
 538            ACE_UINT16 crc = 0);
 539
 540   /// Computes CRC-CCITT for the @ len iovec buffers.
 541   extern ACE_Export ACE_UINT16 crc_ccitt(const iovec *iov, int len,
 542            ACE_UINT16 crc = 0);
 543
 544   /// Computes the ISO 8802-3 standard 32 bits CRC for the string.
 545   extern ACE_Export ACE_UINT32 crc32 (const char *str);
 546
 547   /// Computes the ISO 8802-3 standard 32 bits CRC for the buffer.
 548   extern ACE_Export ACE_UINT32 crc32 (const void *buf, size_t len,
 549               ACE_UINT32 crc = 0);
 550
 551   /// Computes the ISO 8802-3 standard 32 bits CRC for the
 552   /// @ len iovec buffers.
 553   extern ACE_Export ACE_UINT32 crc32 (const iovec *iov, int len,
 554               ACE_UINT32 crc = 0);
 555
 556   /// Euclid's greatest common divisor algorithm.
 557   extern ACE_Export u_long gcd (u_long x, u_long y);
 558
 559   /// Calculates the minimum enclosing frame size for the given values.
 560   extern ACE_Export u_long minimum_frame_size (u_long period1, u_long period2);
 561
 562   /**
 563    * Function that can burn up noticeable CPU time:  brute-force
 564    * determination of whether number @a n is prime.  Returns 0 if
 565    * it is prime, or the smallest factor if it is not prime.
 566    * @a min_factor and @a max_factor can be used to partition the work
 567    * among threads. For just one thread, typical values are 2 and
 568    * n/2.
 569    */
 570   extern ACE_Export u_long is_prime (const u_long n,
 571                                      const u_long min_factor,
 572                                      const u_long max_factor);
 573
 574   /// Map troublesome win32 errno values to values that standard C
 575   /// strerr function understands.  Thank you Microsoft.
 576   extern ACE_Export int map_errno (int error);
 577
 578   /// Returns a string containing the error message corresponding to a
 579   /// WinSock error.  This works around an omission in the Win32 API.
 580   /// @internal
 581   extern ACE_Export const ACE_TCHAR * sock_error (int error);
 582
 583   /// Determins whether the given error code corresponds to to a
 584   /// WinSock error. If so returns true, false otherwise.
 585   /// @internal
 586   extern ACE_Export bool is_sock_error (int error);
 587
 588   /**
 589    * Checks if process with {pid} is still alive.  Returns 1 if it is
 590    * still alive, 0 if it isn't alive, and -1 if something weird
 591    * happened.
 592    */
 593   extern ACE_Export int process_active (pid_t pid);
 594
 595   /**
 596    * Terminate the process abruptly with id @a pid.  On Win32 platforms
 597    * this uses {TerminateProcess} and on POSIX platforms is uses
 598    * {kill} with the -9 (SIGKILL) signal, which cannot be caught or
 599    * ignored.  Note that this call is potentially dangerous to use
 600    * since the process being terminated may not have a chance to
 601    * cleanup before it shuts down.
 602    */
 603   extern ACE_Export int terminate_process (pid_t pid);
 604
 605   /**
 606    * This method uses process id and object pointer to come up with a
 607    * machine wide unique name.  The process ID will provide uniqueness
 608    * between processes on the same machine. The "this" pointer of the
 609    * {object} will provide uniqueness between other "live" objects in
 610    * the same process. The uniqueness of this name is therefore only
 611    * valid for the life of {object}.
 612    */
 613   ACE_NAMESPACE_INLINE_FUNCTION void unique_name (const void *object,
 614                                                   ACE_TCHAR *name,
 615                                                   size_t length);
 616
 617   /// Computes the base 2 logarithm of {num}.
 618   ACE_NAMESPACE_INLINE_FUNCTION u_long log2 (u_long num);
 619
 620   /// Hex conversion utility.
 621   ACE_NAMESPACE_INLINE_FUNCTION ACE_TCHAR nibble2hex (u_int n);
 622
 623   /// Convert a hex character to its byte representation.
 624   ACE_NAMESPACE_INLINE_FUNCTION u_char hex2byte (ACE_TCHAR c);
 625
 626   // = Set/get the debug level.
 627   extern ACE_Export bool debug (void);
 628   extern ACE_Export void debug (bool onoff);
 629
 630   /// Wrapper facade for @c select that uses @c ACE_Handle_Sets.
 631   extern ACE_Export int select (int width,
 632                                 ACE_Handle_Set *readfds,
 633                                 ACE_Handle_Set *writefds = 0,
 634                                 ACE_Handle_Set *exceptfds = 0,
 635                                 const ACE_Time_Value *timeout = 0);
 636
 637   /// Wrapper facade for the most common use of @c select that uses
 638   /// @c ACE_Handle_Sets.
 639   extern ACE_Export int select (int width,
 640                                 ACE_Handle_Set &readfds,
 641                                 const ACE_Time_Value *timeout = 0);
 642
 643   /// Timed wait for handle to get read ready.
 644   ACE_NAMESPACE_INLINE_FUNCTION
 645   int handle_read_ready (ACE_HANDLE handle,
 646                          const ACE_Time_Value *timeout);
 647
 648   /// Timed wait for handle to get write ready.
 649   ACE_NAMESPACE_INLINE_FUNCTION
 650   int handle_write_ready (ACE_HANDLE handle,
 651                           const ACE_Time_Value *timeout);
 652
 653   /// Timed wait for handle to get exception ready.
 654   ACE_NAMESPACE_INLINE_FUNCTION
 655   int handle_exception_ready (ACE_HANDLE handle,
 656                               const ACE_Time_Value *timeout);
 657
 658   /// Timed wait for handle to get read, write, or exception ready.
 659   extern ACE_Export int handle_ready (ACE_HANDLE handle,
 660                                       const ACE_Time_Value *timeout,
 661                                       int read_ready,
 662                                       int write_ready,
 663                                       int exception_ready);
 664
 665   /// Wait for @a timeout before proceeding to a @c recv operation.
 666   /// @a val keeps track of whether we're in non-blocking mode or
 667   /// not.
 668   extern ACE_Export int enter_recv_timedwait (ACE_HANDLE handle,
 669                                               const ACE_Time_Value *timeout,
 670                                               int &val);
 671
 672   /// Wait for @a timeout before proceeding to a @c send operation.
 673   /// @a val keeps track of whether we're in non-blocking mode or
 674   /// not.
 675   extern ACE_Export int enter_send_timedwait (ACE_HANDLE handle,
 676                                               const ACE_Time_Value* timeout,
 677                                               int &val);
 678
 679   /// This makes sure that @a handle is set into non-blocking mode.
 680   /// @a val keeps track of whether were in non-blocking mode or not.
 681   extern ACE_Export void record_and_set_non_blocking_mode (ACE_HANDLE handle,
 682                                                            int &val);
 683
 684   /// Cleanup after a timed operation, restore the appropriate
 685   /// non-blocking status of @a handle.
 686   extern ACE_Export void restore_non_blocking_mode (ACE_HANDLE handle,
 687                                                     int val);
 688
 689   // private:
 690   //   These functions aren't meant to be used internally, so they are
 691   //   not exported.
 692
 693   //
 694   // = Recv_n helpers
 695   //
 696
 697   ACE_NAMESPACE_INLINE_FUNCTION ssize_t recv_i (ACE_HANDLE handle,
 698                                                 void *buf,
 699                                                 size_t len);
 700
 701   extern ACE_Export ssize_t recv_n_i (ACE_HANDLE handle,
 702                                       void *buf,
 703                                       size_t len,
 704                                       int flags,
 705                                       size_t *bytes_transferred);
 706
 707   extern ACE_Export ssize_t recv_n_i (ACE_HANDLE handle,
 708                                       void *buf,
 709                                       size_t len,
 710                                       int flags,
 711                                       const ACE_Time_Value *timeout,
 712                                       size_t *bytes_transferred);
 713
 714 #if defined (ACE_HAS_TLI)
 715
 716   extern ACE_Export ssize_t t_rcv_n_i (ACE_HANDLE handle,
 717                                        void *buf,
 718                                        size_t len,
 719                                        int *flags,
 720                                        size_t *bytes_transferred);
 721
 722   extern ACE_Export ssize_t t_rcv_n_i (ACE_HANDLE handle,
 723                                        void *buf,
 724                                        size_t len,
 725                                        int *flags,
 726                                        const ACE_Time_Value *timeout,
 727                                        size_t *bytes_transferred);
 728
 729 #endif /* ACE_HAS_TLI */
 730
 731   extern ACE_Export ssize_t recv_n_i (ACE_HANDLE handle,
 732                                       void *buf,
 733                                       size_t len,
 734                                       size_t *bytes_transferred);
 735
 736   extern ACE_Export ssize_t recv_n_i (ACE_HANDLE handle,
 737                                       void *buf,
 738                                       size_t len,
 739                                       const ACE_Time_Value *timeout,
 740                                       size_t *bytes_transferred);
 741
 742   extern ACE_Export ssize_t recvv_n_i (ACE_HANDLE handle,
 743                                        iovec *iov,
 744                                        int iovcnt,
 745                                        size_t *bytes_transferred);
 746
 747   extern ACE_Export ssize_t recvv_n_i (ACE_HANDLE handle,
 748                                        iovec *iov,
 749                                        int iovcnt,
 750                                        const ACE_Time_Value *timeout,
 751                                        size_t *bytes_transferred);
 752
 753   //
 754   // = Send_n helpers
 755   //
 756
 757   ACE_NAMESPACE_INLINE_FUNCTION ssize_t send_i (ACE_HANDLE handle,
 758                                                 const void *buf,
 759                                                 size_t len);
 760
 761   extern ACE_Export ssize_t send_n_i (ACE_HANDLE handle,
 762                                       const void *buf,
 763                                       size_t len,
 764                                       int flags,
 765                                       size_t *bytes_transferred);
 766
 767   extern ACE_Export ssize_t send_n_i (ACE_HANDLE handle,
 768                                       const void *buf,
 769                                       size_t len,
 770                                       int flags,
 771                                       const ACE_Time_Value *timeout,
 772                                       size_t *bytes_transferred);
 773
 774 #if defined (ACE_HAS_TLI)
 775
 776   extern ACE_Export ssize_t t_snd_n_i (ACE_HANDLE handle,
 777                                        const void *buf,
 778                                        size_t len,
 779                                        int flags,
 780                                        size_t *bytes_transferred);
 781
 782   extern ACE_Export ssize_t t_snd_n_i (ACE_HANDLE handle,
 783                                        const void *buf,
 784                                        size_t len,
 785                                        int flags,
 786                                        const ACE_Time_Value *timeout,
 787                                        size_t *bytes_transferred);
 788
 789 #endif /* ACE_HAS_TLI */
 790
 791   extern ACE_Export ssize_t send_n_i (ACE_HANDLE handle,
 792                                       const void *buf,
 793                                       size_t len,
 794                                       size_t *bytes_transferred);
 795
 796   extern ACE_Export ssize_t send_n_i (ACE_HANDLE handle,
 797                                       const void *buf,
 798                                       size_t len,
 799                                       const ACE_Time_Value *timeout,
 800                                       size_t *bytes_transferred);
 801
 802   extern ACE_Export ssize_t sendv_n_i (ACE_HANDLE handle,
 803                                        const iovec *iov,
 804                                        int iovcnt,
 805                                        size_t *bytes_transferred);
 806
 807   extern ACE_Export ssize_t sendv_n_i (ACE_HANDLE handle,
 808                                        const iovec *iov,
 809                                        int iovcnt,
 810                                        const ACE_Time_Value *timeout,
 811                                        size_t *bytes_transferred);
 812
 813 }
 814
 815 // Close versioned namespace, if enabled by the user.
 816 ACE_END_VERSIONED_NAMESPACE_DECL
 817
 818 #if defined (__ACE_INLINE__)
 819 #include "ace/ACE.inl"
 820 #endif /* __ACE_INLINE__ */
 821
 822 #include /**/ "ace/post.h"
 823
 824 #endif  /* ACE_ACE_H */