.\"macro stdmacro
.\"
.\" Copyright (c) 2021 Ken McDonell.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMSTRNCAT 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmstrncat\f1 \- safe string concatenation
.SH "C SYNOPSIS"
.ft 3
.ad l
.hy 0
#include <pcp/pmapi.h>
.sp
int pmstrncat(char *\fIdest\fP, size_t \fIdestlen\fP, char *\fIsrc\fP);
.sp
cc ... \-lpcp
.hy
.ad
.ft 1
.SH DESCRIPTION
.B pmstrncat
is safe string concatenation routine with semantics similar to
.BR strncat (3).
.PP
The main differences between
.B pmstrncat
and
.BR strncat (3)
are:
.PD 0
.IP \(bu 2n
.I src
must be null-byte terminated for
.B pmstrncat
.IP \(bu 2n
.I destlen
is the length of the destination buffer (\c
.IR dest )
for
.B pmstrncat,
not the maximum number of non-null bytes to copy from
.IR src
as it is for
.B strncat
.IP \(bu 2n
the length
argument has the same semantics for
.B pmstrncat
and
.BR pmstrncpy (3),
unlike
.BR strncat (3)
and
.BR strncpy (3).
.IP \(bu 2n
the return value from
.B pmstrncat
is useful
.IP \(bu 2n
the order of the arguments for
.B pmstrncat
has been
.I deliberately
changed from the order of the arguments for
.BR strncat (3)
to avoid accidental misuse that a compiler can easily
detect
.PD
.PP
On success,
.B pmstrncat
returns 0, else -1 indicates that
.I src
is too big and the result been truncated to ensure
.I dest
has not been overrun.
.SH HISTORY
.BR strncat (3)
first appeared in Edition 7 AT&T Unix around 1979.
It was specifically crafted to construct file pathnames (which needed
to be null-byte terminated) from component names from on-disk directory
entries that were of a fixed maximum size and may have zero, one or more
trailing null-bytes
.PP
The subsequent attempts to use
.BR strncat (3)
for more generally string concatenation operations has been
fraught with abuse and security issues;
.BR pmstrncat
is an attempt to address these problems.
.SH SEE ALSO
.BR PMAPI (3),
.BR pmstrncpy (3),
.BR strncat (3)
and
.BR strncpy (3).