root/opal/util/string_copy.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM

   1 /*
   2  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
   3  *                         University Research and Technology
   4  *                         Corporation.  All rights reserved.
   5  * Copyright (c) 2004-2006 The University of Tennessee and The University
   6  *                         of Tennessee Research Foundation.  All rights
   7  *                         reserved.
   8  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
   9  *                         University of Stuttgart.  All rights reserved.
  10  * Copyright (c) 2004-2005 The Regents of the University of California.
  11  *                         All rights reserved.
  12  * $COPYRIGHT$
  13  *
  14  * Additional copyrights may follow
  15  *
  16  * $HEADER$
  17  */
  18 
  19 #ifndef OPAL_STRING_COPY_H
  20 #define OPAL_STRING_COPY_H
  21 
  22 #include "opal_config.h"
  23 #ifdef HAVE_SYS_TYPES_H
  24 #include <sys/types.h>
  25 #endif
  26 
  27 BEGIN_C_DECLS
  28 
  29 /**
  30  * Do a "safe" string copy (i.e., guarantee to \0-terminate the
  31  * destination string), and assert() fail if the copy length is too
  32  * large (because we assume it is a programmer error).
  33  *
  34  * @param dest Destination string buffer.
  35  * @param src Source string buffer.
  36  * @param dest_len Length of the destination string buffer.
  37  *
  38  * This function is similar to, but different than, strcpy() and
  39  * strncpy().
  40  *
  41  * It is invalid to pass NULL for either dest or src.
  42  *
  43  * If dest_len is larger than
  44  * OPAL_MAX_SIZE_ALLOWED_BY_OPAL_STRING_COPY, we assume that this is
  45  * a programmer error (because Open MPI does not generally need to do
  46  * large string copies), and will assert() fail / abort.
  47  *
  48  * There is no return value.
  49  *
  50  * This function will essentially do the same thing as strncpy(),
  51  * except that a) it will guarantee to to terminate the destination
  52  * string with a \0, and b) it will not \0-pad to the right.
  53  * Specifically:
  54  *
  55  * - If the length of the source string is less than (len), the entire
  56  *   source string will be copied to the destination, including the
  57  *   \0.
  58  * - If the length of the source string is greater than (len), then
  59  *   (len-1) characters of the source string will be copied to the
  60  *   destination, and dest[len-1] will be set to '\0'.
  61  */
  62 OPAL_DECLSPEC void opal_string_copy(char *dest, const char *src,
  63                                     size_t dest_len)
  64     __opal_attribute_nonnull__(1) __opal_attribute_nonnull__(2);
  65 
  66 /**
  67  * Max dest_size allowed by opal_string_copy().
  68  *
  69  * See the description of opal_string_copy() for an explanation.
  70  */
  71 #define OPAL_MAX_SIZE_ALLOWED_BY_OPAL_STRING_COPY (128 * 1024)
  72 
  73 END_C_DECLS
  74 
  75 #endif /* OPAL_STRING_COPY_H */
/* [<][>][^][v][top][bottom][index][help] */