ACE/ace/ACE.h

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