From: Alejandro Colomar <alx.manpages@gmail.com>
To: Stefan Puiu <stefan.puiu@gmail.com>
Cc: linux-man@vger.kernel.org, Alejandro Colomar <alx@kernel.org>,
Martin Sebor <msebor@redhat.com>,
"G. Branden Robinson" <g.branden.robinson@gmail.com>,
Douglas McIlroy <douglas.mcilroy@dartmouth.edu>,
Jakub Wilk <jwilk@jwilk.net>, Serge Hallyn <serge@hallyn.com>,
Iker Pedrosa <ipedrosa@redhat.com>,
Andrew Pinski <pinskia@gmail.com>
Subject: Re: [PATCH v5 2/5] stpecpy.3, stpecpyx.3, ustpcpy.3, ustr2stp.3, zustr2stp.3, zustr2ustp.3: Add new links to string_copy(7)
Date: Fri, 16 Dec 2022 20:03:53 +0100 [thread overview]
Message-ID: <5abac28c-e8fa-d62b-2211-5ddd6820e882@gmail.com> (raw)
In-Reply-To: <CACKs7VDYWBaMtAELqnV31eJjRNebPH-m9kZiXXq4fABgvQ+E5Q@mail.gmail.com>
[-- Attachment #1.1: Type: text/plain, Size: 8165 bytes --]
Hi Stefan,
On 12/16/22 19:47, Stefan Puiu wrote:
> Hi Alex!
>
> On Thu, Dec 15, 2022 at 2:46 AM Alejandro Colomar
> <alx.manpages@gmail.com> wrote:
>>
>> Formatted strpcy(3):
>>
>> strcpy(3) Library Functions Manual strcpy(3)
>>
>> NAME
>> strcpy - copy or catenate a string
>>
>> LIBRARY
>> Standard C library (libc, -lc)
>>
>> SYNOPSIS
>> #include <string.h>
>>
>> char *stpcpy(char *restrict dst, const char *restrict src);
>> char *strcpy(char *restrict dst, const char *restrict src);
>> char *strcat(char *restrict dst, const char *restrict src);
>>
>> Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
>>
>> stpcpy():
>> Since glibc 2.10:
>> _POSIX_C_SOURCE >= 200809L
>> Before glibc 2.10:
>> _GNU_SOURCE
>>
>> DESCRIPTION
>> stpcpy()
>> strcpy()
>> These functions copy the string pointed to by src, into a string
>> at the buffer pointed to by dst. The programmer is responsible
>> for allocating a buffer large enough, that is, strlen(src) + 1.
>> They only differ in the return value.
>
> A destination buffer large enough? It's not that obvious to me from
> the text, but maybe I'm tired :).
Sure. Thanks!
> I was also a bit at a loss about the difference between the two; maybe
> you can say "For the difference between the two, see RETURN VALUE"?
That can make sense, yes.
>
>>
>> strcat()
>> This function catenates the string pointed to by src, at the end
>> of the string pointed to by dst. The programmer is responsible
>> for allocating a buffer large enough, that is, strlen(dst) +
>> strlen(src) + 1.
>
> Ditto here.
:)
>
>>
>> An implementation of these functions might be:
>>
>> char *
>> stpcpy(char *restrict dst, const char *restrict src)
>> {
>> char *end;
>>
>> end = mempcpy(dst, src, strlen(src));
>> *end = '\0';
>>
>> return end;
>> }
>>
>> char *
>> strcpy(char *restrict dst, const char *restrict src)
>> {
>> stpcpy(dst, src);
>> return dst;
>> }
>>
>> char *
>> strcat(char *restrict dst, const char *restrict src)
>> {
>> stpcpy(dst + strlen(dst), src);
>> return dst;
>> }
>
> Are you sure this section adds any value? I think good documentation
> should explain how a function works without delving into the
> interpretation.
To be honest, this page doesn't benefit too much from it. strcpy(3)/strcat(3)
are dead simple, and the explanations above should be enough.
However, the same thing in strncpy(3) and strncat(3) is very helpful, IMO. For
consistency I just showed trivial implementations in all of the pages. (And in
fact, there was an example implementation in the old strncat(3) and maybe a few
others, IIRC.)
> Also, people might get confused and think this is the
> actual implementation.
I don't think there's any problem if one believes this is the implementation.
Except for stpcpy(3), in which I preferred readability, they are actually quite
good implementations. A faster implementation of stpcpy(3) might be done in
terms of memccpy(3).
Funnily enough, I just checked what musl libc does, and it's the same as shown here:
alx@debian:~/src/musl/musl$ grepc -tfd strcpy
./src/string/strcpy.c:3:
char *strcpy(char *restrict dest, const char *restrict src)
{
__stpcpy(dest, src);
return dest;
}
alx@debian:~/src/musl/musl$ grepc -tfd strcat
./src/string/strcat.c:3:
char *strcat(char *restrict dest, const char *restrict src)
{
strcpy(dest + strlen(dest), src);
return dest;
}
>
>>
>> RETURN VALUE
>> stpcpy()
>> This function returns a pointer to the terminating null byte at
>> the end of the copied string.
>>
>> strcpy()
>> strcat()
>> These functions return dest.
>>
>> ATTRIBUTES
>> For an explanation of the terms used in this section, see attrib‐
>> utes(7).
>> ┌────────────────────────────────────────────┬───────────────┬─────────┐
>> │Interface │ Attribute │ Value │
>> ├────────────────────────────────────────────┼───────────────┼─────────┤
>> │stpcpy(), strcpy(), strcat() │ Thread safety │ MT‐Safe │
>> └────────────────────────────────────────────┴───────────────┴─────────┘
>>
>> STANDARDS
>> stpcpy()
>> POSIX.1‐2008.
>>
>> strcpy()
>> strcat()
>> POSIX.1‐2001, POSIX.1‐2008, C89, C99, SVr4, 4.3BSD.
>>
>> CAVEATS
>> The strings src and dst may not overlap.
>>
>> If the destination buffer is not large enough, the behavior is unde‐
>> fined. See _FORTIFY_SOURCE in feature_test_macros(7).
>>
>> BUGS
>> strcat()
>> This function can be very inefficient. Read about Shlemiel
>> the painter ⟨https://www.joelonsoftware.com/2001/12/11/
>> back-to-basics/⟩.
>
> I'm not sure this is a bug, rather a design limitation. Maybe it
> belongs in NOTES or CAVEATS?
Yeah, I had been thinking of downgrading it. I'll do it.
> Also, I think this can be summarized
> along the lines of 'strcat needs to walk the destination buffer to
> find the null terminator, so it has linear complexity with respect to
> the size of the destination buffer up to the terminator' (hmm, I'm
> sure this can be expressed more concisely), so the page is more self
> contained. Outside links sometimes go dead, like on Wikipedia, so I
> think just in case, it helps to make explicit the point that you want
> the reader to study further in the URL.
I wasn't inspired to write it short enough to not be too verbose. Maybe I'll
write something based on your suggestion.
>
> Regards,
> Stefan.
Thanks for the review!
Cheers,
Alex
>
>>
>> EXAMPLES
>> #include <stdio.h>
>> #include <stdlib.h>
>> #include <string.h>
>>
>> int
>> main(void)
>> {
>> char *p;
>> char buf1[BUFSIZ];
>> char buf2[BUFSIZ];
>> size_t len;
>>
>> p = buf1;
>> p = stpcpy(p, "Hello ");
>> p = stpcpy(p, "world");
>> p = stpcpy(p, "!");
>> len = p - buf1;
>>
>> printf("[len = %zu]: ", len);
>> puts(buf1); // "Hello world!"
>>
>> strcpy(buf2, "Hello ");
>> strcat(buf2, "world");
>> strcat(buf2, "!");
>> len = strlen(buf2);
>>
>> printf("[len = %zu]: ", len);
>> puts(buf2); // "Hello world!"
>>
>> exit(EXIT_SUCCESS);
>> }
>>
>> SEE ALSO
>> strdup(3), string(3), wcscpy(3), string_copy(7)
>>
>> Linux man‐pages (unreleased) (date) strcpy(3)
>>
>> --
>> <http://www.alejandro-colomar.es/>
--
<http://www.alejandro-colomar.es/>
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next prev parent reply other threads:[~2022-12-16 19:04 UTC|newest]
Thread overview: 53+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-12-11 23:59 string_copy(7): New manual page documenting string copying functions Alejandro Colomar
2022-12-12 0:17 ` Alejandro Colomar
2022-12-12 0:25 ` Alejandro Colomar
2022-12-12 0:32 ` Alejandro Colomar
2022-12-12 14:24 ` [PATCH 1/3] strcpy.3: Rewrite page to document all string-copying functions Alejandro Colomar
2022-12-12 17:33 ` Alejandro Colomar
2022-12-12 18:38 ` groff man(7) extensions (was: [PATCH 1/3] strcpy.3: Rewrite page to document all string-copying functions) G. Branden Robinson
2022-12-13 15:45 ` a Q quotation macro for man(7) (was: groff man(7) extensions) G. Branden Robinson
2022-12-12 23:00 ` [PATCH v2 0/3] Rewrite strcpy(3) Alejandro Colomar
2022-12-13 20:56 ` Jakub Wilk
2022-12-13 20:57 ` Alejandro Colomar
2022-12-13 22:05 ` Alejandro Colomar
2022-12-13 22:46 ` Alejandro Colomar
2022-12-14 0:03 ` [PATCH v3 0/1] Rewritten page for string-copying functions Alejandro Colomar
2022-12-14 0:14 ` Alejandro Colomar
2022-12-14 0:16 ` Alejandro Colomar
2022-12-14 16:17 ` [PATCH v4 " Alejandro Colomar
2022-12-15 0:26 ` [PATCH v5 0/5] Rewrite pages about " Alejandro Colomar
2022-12-19 21:02 ` [PATCH v6 0/5] Rewrite documentation for " Alejandro Colomar
2022-12-19 21:02 ` [PATCH v6 1/5] string_copy.7: Add page to document all " Alejandro Colomar
2022-12-20 15:00 ` Stefan Puiu
2022-12-20 15:03 ` Alejandro Colomar
2023-01-20 3:43 ` Eric Biggers
2023-01-20 12:55 ` Alejandro Colomar
2022-12-19 21:02 ` [PATCH v6 2/5] stpecpy.3, stpecpyx.3, ustpcpy.3, ustr2stp.3, zustr2stp.3, zustr2ustp.3: Add new links to string_copy(7) Alejandro Colomar
2022-12-19 21:02 ` [PATCH v6 3/5] stpcpy.3, strcpy.3, strcat.3: Document in a single page Alejandro Colomar
2022-12-19 21:02 ` [PATCH v6 4/5] stpncpy.3, strncpy.3: " Alejandro Colomar
2022-12-19 21:02 ` [PATCH v6 5/5] strncat.3: Rewrite to be consistent with string_copy.7 Alejandro Colomar
2022-12-15 0:26 ` [PATCH v5 1/5] string_copy.7: Add page to document all string-copying functions Alejandro Colomar
2022-12-15 0:30 ` Alejandro Colomar
2022-12-15 0:26 ` [PATCH v5 2/5] stpecpy.3, stpecpyx.3, ustpcpy.3, ustr2stp.3, zustr2stp.3, zustr2ustp.3: Add new links to string_copy(7) Alejandro Colomar
2022-12-15 0:27 ` Alejandro Colomar
2022-12-16 18:47 ` Stefan Puiu
2022-12-16 19:03 ` Alejandro Colomar [this message]
2022-12-16 19:09 ` Alejandro Colomar
2022-12-15 0:26 ` [PATCH v5 3/5] stpcpy.3, strcpy.3, strcat.3: Document in a single page Alejandro Colomar
2022-12-16 14:46 ` Alejandro Colomar
2022-12-16 14:47 ` Alejandro Colomar
2022-12-15 0:26 ` [PATCH v5 4/5] stpncpy.3, strncpy.3: " Alejandro Colomar
2022-12-15 0:28 ` Alejandro Colomar
2022-12-15 0:26 ` [PATCH v5 5/5] strncat.3: Rewrite to be consistent with string_copy.7 Alejandro Colomar
2022-12-15 0:29 ` Alejandro Colomar
2022-12-14 16:17 ` [PATCH v4 1/1] strcpy.3: Rewrite page to document all string-copying functions Alejandro Colomar
2022-12-14 0:03 ` [PATCH v3 " Alejandro Colomar
2022-12-14 16:22 ` Douglas McIlroy
2022-12-14 16:36 ` Alejandro Colomar
2022-12-14 17:11 ` Alejandro Colomar
2022-12-14 17:19 ` Alejandro Colomar
2022-12-12 23:00 ` [PATCH v2 1/3] " Alejandro Colomar
2022-12-12 23:00 ` [PATCH v2 2/3] stpcpy.3, stpncpy.3, strcat.3, strncat.3, strncpy.3: Transform the old pages into links to strcpy(3) Alejandro Colomar
2022-12-12 23:00 ` [PATCH v2 3/3] stpecpy.3, stpecpyx.3, strlcat.3, strlcpy.3, strscpy.3: Add new " Alejandro Colomar
2022-12-12 14:24 ` [PATCH 2/3] stpcpy.3, stpncpy.3, strcat.3, strncat.3, strncpy.3: Transform the old pages into " Alejandro Colomar
2022-12-12 14:24 ` [PATCH 3/3] stpecpy.3, stpecpyx.3, strlcat.3, strlcpy.3, strscpy.3: Add new " 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=5abac28c-e8fa-d62b-2211-5ddd6820e882@gmail.com \
--to=alx.manpages@gmail.com \
--cc=alx@kernel.org \
--cc=douglas.mcilroy@dartmouth.edu \
--cc=g.branden.robinson@gmail.com \
--cc=ipedrosa@redhat.com \
--cc=jwilk@jwilk.net \
--cc=linux-man@vger.kernel.org \
--cc=msebor@redhat.com \
--cc=pinskia@gmail.com \
--cc=serge@hallyn.com \
--cc=stefan.puiu@gmail.com \
/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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.