.\"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 PMSTRNCPY 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmstrncpy\f1 \- safe string copy
.SH "C SYNOPSIS"
.ft 3
.ad l
.hy 0
#include <pcp/pmapi.h>
.sp
int pmstrncpy(char *\fIdest\fP, size_t \fIdestlen\fP, char *\fIsrc\fP);
.sp
cc ... \-lpcp
.hy
.ad
.ft 1
.SH DESCRIPTION
.B pmstrncpy
is safe string copying routine with semantics similar to
.BR strncpy (3).
.PP
The main differences between
.B pmstrncpy
and
.BR strncpy (3)
are:
.PD 0
.IP \(bu 2n
.I src
must be null-byte terminated for
.B pmstrncpy
.IP \(bu 2n
.B pmstrncpy
ensures that
.I dest
is null-byte terminated, even when
.I src
is larger than
.IR destlen ;
this may result in
truncated copying of
.I src
.IP \(bu 2n
when
.I src
is shorter than
.I destlen
.B pmstrncpy
does not null-byte fill the remainder of
.I dest
after
.I src
has been copied and null-byte terminated
.IP \(bu 2n
the length
argument has the same semantics for
.B pmstrncpy
and
.BR pmstrncat (3),
unlike
.BR strncpy (3)
and
.BR strncat (3).
.IP \(bu 2n
the return value from
.B pmstrncpy
is useful
.IP \(bu 2n
the order of the arguments for
.B pmstrncpy
has been
.I deliberately
changed from the order of the arguments for
.BR strncpy (3)
to avoid accidental misuse that a compiler can easily
detect
.PD
.PP
On success,
.B pmstrncpy
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 strncpy (3)
first appeared in Edition 7 AT&T Unix around 1979.
It was specifically crafted to copy file names
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 strncpy (3)
for more generally string copying operations has been
fraught with abuse and security issues;
.BR pmstrncpy
is an attempt to address these problems.
.SH SEE ALSO
.BR PMAPI (3),
.BR pmstrncat (3),
.BR strncat (3)
and
.BR strncpy (3).