From: Alejandro Colomar <alx.manpages@gmail.com>
To: libc-alpha@sourceware.org
Cc: Alejandro Colomar <alx@kernel.org>
Subject: [PATCH 0/1] string: Add stpecpy(3)
Date: Thu, 22 Dec 2022 22:42:17 +0100 [thread overview]
Message-ID: <20221222214217.1619716-1-alx@kernel.org> (raw)
Hi!
I recently rewrite the Linux man-pages for string-copying functions, and
just a moment ago, I released the new version. There are some important
gaps in the string-copying library, and they should be addressed,
however it is done, but ignoring it won't solve the problem.
I know this has been suggested in the past (I did once), and has never
progressed, but I'll try to justify it as much as I can.
The gaps are:
- No function for copying strings with truncation. (strlcpy(3) or strscpy(9))
- No function for catenating strings with truncation. (strlcat(3))
- No function for chain-copying strings with truncation. (stpecpy(3))
This is similar to strcpy(3)/strcat(3)/stpcpy(3), where stpcpy(3) is
faster and more versatile than the other two, but it's also slightly
more complex to use (only slightly).
We wouldn't need to add the 3, but at least stpecpy(3) or both
strlcpy(3) and strlcat(3).
Since stpecpy(3) is significantly faster than the other two, I
suggest at least adding stpecpy(3). Also, strlcpy(3)/cat(3) can be
more easily implemented in terms of stpecpy(3).
There are a few other gaps, but they are much less important, since
there are relatively good workarounds. I don't want to overload the
discussion either, so I prefer first adding the most necessary function,
and only after that deciding if we want to support other string-copying
functions.
I had added this function this week to a new string library that I was
writing, so I already had a manual page written for it. I'll copy it
below, to document all the details of the API.o
Cheers,
Alex
---
Alejandro Colomar (1):
string: Add stpecpy(3)
string/Makefile | 1 +
string/stpecpy.c | 39 +++++++++++++++++++++++++++++++++++++++
string/string.h | 7 +++++++
3 files changed, 47 insertions(+)
create mode 100644 string/stpecpy.c
stpecpy(3) Library Functions Manual stpecpy(3)
NAME
stpecpy, stpecpyx - copy a string with truncation
LIBRARY
Stp string library (libstp, pkgconf ‐‐cflags ‐‐libs libstp)
SYNOPSIS
#include <stp/stpe/stpecpy.h>
char *_Nullable stpecpy(char *_Nullable dst, char end[0],
const char *restrict src);
char *_Nullable stpecpyx(char *_Nullable dst, char end[0],
const char *restrict src);
DESCRIPTION
These functions copy the string pointer to by src, into a string at the
buffer pointer to by dst. If the destination buffer, limited by a
pointer to its end —one after its last element—, isn’t large enough to
hold the copy, the resulting string is truncated.
stpecpyx(3) forces a SIGSEGV if the input is not a string, by travers‐
ing it entirely.
These functions can be chained with calls to stpeprintf(3) and
vstpeprintf(3).
An implementation of these functions might be
/* This code is in the public domain. */
char *
stpecpy(char *dst, char end[0], const char *restrict src)
{
char *p;
if (dst == end || dst == NULL)
return dst;
p = memccpy(dst, src, '\0', end - dst);
if (p != NULL)
return p - 1;
/* truncation detected */
end[-1] = '\0';
return end;
}
char *
stpecpyx(char *dst, char end[0], const char *restrict src)
{
if (src[strlen(src)] != '\0')
raise(SIGSEGV);
return stpecpy(dst, end, src);
}
RETURN VALUE
NULL If dst was NULL.
end
• If this call truncated.
• If dst was equal to end (a previous call to these functions
truncated).
dst + strlen(dst)
On success, these functions return a pointer to the terminating
null byte.
ATTRIBUTES
For an explanation of the terms used in this section, see attrib‐
utes(7).
┌────────────────────────────────────────────┬───────────────┬─────────┐
│Interface │ Attribute │ Value │
├────────────────────────────────────────────┼───────────────┼─────────┤
│stpecpy(3), stpecpyx(3) │ Thread safety │ MT‐Safe │
└────────────────────────────────────────────┴───────────────┴─────────┘
STANDARDS
None.
EXAMPLES
$ cc ./stpecpy.c $(pkgconf --cflags --libs libbsd-overlay libstp)
$ ./a.out
[len = 12]: Hello world!
$
// stpecpy.c
#include <err.h>
#include <stdio.h>
#include <stdlib.h>
#include <stp/stpecpy.h>
#include <stp/stpeprintf.h>
int
main(void)
{
char *p, *end;
char buf[BUFSIZ];
size_t len;
end = buf + BUFSIZ;
p = buf;
p = stpecpy(p, end, "Hello, ");
p = stpeprintf(p, end, "%d worlds", 22);
p = stpecpy(p, end, "!");
if (p == NULL)
err(EXIT_FAILURE, "stpeprintf()");
if (p == end) {
p--;
warnx("Truncated");
}
len = p - buf;
printf("[len = %zu]: ", len);
puts(buf);
exit(EXIT_SUCCESS);
}
SEE ALSO
stpeprintf(3), string_copying(7)
libstp (unreleased) (date) stpecpy(3)
--
2.39.0
next reply other threads:[~2022-12-22 21:42 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-12-22 21:42 Alejandro Colomar [this message]
2022-12-22 21:42 ` [PATCH 1/1] " Alejandro Colomar
2022-12-23 7:02 ` Sam James
2022-12-23 12:26 ` Alejandro Colomar
2022-12-23 12:29 ` Alejandro Colomar
2022-12-23 17:21 ` Alejandro Colomar
2022-12-31 15:13 ` Sam James
2022-12-31 15:15 ` Alejandro Colomar
2022-12-28 23:17 ` [PATCH v2 0/3] Add stpe*() functions Alejandro Colomar
2022-12-29 0:01 ` Zack Weinberg
2022-12-29 10:13 ` Alejandro Colomar
2022-12-28 23:17 ` [PATCH v2 1/3] string: Add stpecpy() Alejandro Colomar
2022-12-28 23:27 ` Alejandro Colomar
2022-12-28 23:17 ` [PATCH v2 2/3] stdio: Add vstpeprintf() Alejandro Colomar
2022-12-28 23:17 ` [PATCH v2 3/3] stdio: Add stpeprintf() Alejandro Colomar
2022-12-28 23:27 ` Alejandro Colomar
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20221222214217.1619716-1-alx@kernel.org \
--to=alx.manpages@gmail.com \
--cc=alx@kernel.org \
--cc=libc-alpha@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).