src/util/pmix_string_copy.h

0001 /*
0002  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
0003  *                         University Research and Technology
0004  *                         Corporation.  All rights reserved.
0005  * Copyright (c) 2004-2006 The University of Tennessee and The University
0006  *                         of Tennessee Research Foundation.  All rights
0007  *                         reserved.
0008  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
0009  *                         University of Stuttgart.  All rights reserved.
0010  * Copyright (c) 2004-2005 The Regents of the University of California.
0011  *                         All rights reserved.
0012  * Copyright (c) 2019-2020 Intel, Inc.  All rights reserved.
0013  * Copyright (c) 2020      Cisco Systems, Inc.  All rights reserved
0014  * Copyright (c) 2021-2023 Nanook Consulting.  All rights reserved.
0015  * $COPYRIGHT$
0016  *
0017  * Additional copyrights may follow
0018  *
0019  * $HEADER$
0020  */
0021
0022 #ifndef PMIX_STRING_COPY_H
0023 #define PMIX_STRING_COPY_H
0024
0025 #include "src/include/pmix_config.h"
0026 #include "pmix_common.h"
0027
0028 #ifdef HAVE_SYS_TYPES_H
0029 #    include <sys/types.h>
0030 #endif
0031 #ifdef HAVE_FCNTL_H
0032 #    include <fcntl.h>
0033 #endif
0034 #ifdef HAVE_UNISTD_H
0035 #    include <unistd.h>
0036 #endif
0037
0038 BEGIN_C_DECLS
0039
0040 /**
0041  * Do a "safe" string copy (i.e., guarantee to \0-terminate the
0042  * destination string), and assert() fail if the copy length is too
0043  * large (because we assume it is a programmer error).
0044  *
0045  * @param dest Destination string buffer.
0046  * @param src Source string buffer.
0047  * @param dest_len Length of the destination string buffer.
0048  *
0049  * This function is similar to, but different than, strcpy() and
0050  * strncpy().
0051  *
0052  * It is invalid to pass NULL for either dest or src.
0053  *
0054  * If dest_len is larger than
0055  * PMIX_MAX_SIZE_ALLOWED_BY_PMIX_STRING_COPY, we assume that this is
0056  * a programmer error (because PMIX does not generally need to do
0057  * large string copies), and will assert() fail / abort.
0058  *
0059  * There is no return value.
0060  *
0061  * This function will essentially do the same thing as strncpy(),
0062  * except that a) it will guarantee to to terminate the destination
0063  * string with a \0, and b) it will not \0-pad to the right.
0064  * Specifically:
0065  *
0066  * - If the length of the source string is less than (len), the entire
0067  *   source string will be copied to the destination, including the
0068  *   \0.
0069  * - If the length of the source string is greater than (len), then
0070  *   (len-1) characters of the source string will be copied to the
0071  *   destination, and dest[len-1] will be set to '\0'.
0072  */
0073 PMIX_EXPORT void pmix_string_copy(char *dest, const char *src, size_t dest_len)
0074     __pmix_attribute_nonnull__(1) __pmix_attribute_nonnull__(2);
0075
0076 /**
0077  * Max dest_size allowed by pmix_string_copy().
0078  *
0079  * See the description of pmix_string_copy() for an explanation.
0080  */
0081 #define PMIX_MAX_SIZE_ALLOWED_BY_PMIX_STRING_COPY (128 * 1024)
0082
0083 PMIX_EXPORT char *pmix_getline(FILE *fp);
0084
0085
0086 END_C_DECLS
0087
0088 #endif /* PMIX_STRING_COPY_H */