Skip to content

Commit e071478

Browse files
LancernLancern
committed
feat: add page c.library.memcpy
1 parent 98763ac commit e071478

9 files changed

Lines changed: 254 additions & 63 deletions

File tree

‎src/components/DeclDoc.astro‎

Lines changed: 0 additions & 46 deletions
This file was deleted.

‎src/components/decl-doc/Decl.astro‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
3+
---
4+
5+
<div class="decl">
6+
<slot />
7+
</div>
8+
9+
<style>
10+
.decl {
11+
background-color: var(--sl-color-gray-6);
12+
border-bottom: 1px solid var(--sl-color-gray-5);
13+
overflow: scroll;
14+
margin: 0;
15+
padding: 0 1em;
16+
}
17+
</style>
18+
19+
<style is:global>
20+
.decl .expressive-code pre {
21+
border: none;
22+
background-color: transparent;
23+
font-size: 1rem;
24+
line-height: 1.2;
25+
}
26+
27+
.decl .expressive-code pre code .ec-line .code {
28+
padding: 0;
29+
}
30+
31+
.decl .expressive-code .copy {
32+
display: none;
33+
}
34+
</style>

‎src/components/decl-doc/DeclDoc.astro‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
import AutoCollapse from "../AutoCollapse.astro";
3+
4+
interface Props {
5+
id?: number;
6+
}
7+
8+
const { id } = Astro.props;
9+
const hasId = id !== undefined;
10+
---
11+
12+
<div class="decl-doc">
13+
{hasId ? (
14+
<div class="decl-id">Declaration #{id}</div>
15+
) : <></>}
16+
<slot name="decl" />
17+
<div class="doc">
18+
<AutoCollapse maxHeight={200}>
19+
<slot />
20+
</AutoCollapse>
21+
</div>
22+
</div>
23+
24+
<style>
25+
.decl-doc {
26+
border: 2px solid var(--sl-color-gray-5);
27+
border-top-left-radius: 6px;
28+
border-top-right-radius: 6px;
29+
overflow: hidden;
30+
}
31+
32+
.decl-doc > .decl-id {
33+
text-align: center;
34+
font-size: 0.9em;
35+
color: var(--sl-color-gray-3);
36+
margin: 0;
37+
border-bottom: 1px solid var(--sl-color-gray-5);
38+
}
39+
40+
.decl-doc > .doc {
41+
margin: 1em;
42+
}
43+
</style>

‎src/components/decl-doc/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
export { default as Decl } from "./Decl.astro";
2+
export { default as DeclDoc } from "./DeclDoc.astro";

‎src/content/docs/c/library/strings/_meta.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
label: Strings library

‎src/content/docs/c/library/strings/byte/_meta.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
label: Null-terminate byte strings

‎src/content/docs/c/library/strings/byte/memcpy.mdx‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
title: memcpy, memcpy_s
3+
cppdoc:
4+
keys: ["c.library.memcpy", "c.library.memcpy_s"]
5+
---
6+
7+
import Behavior from "@components/Behavior.astro";
8+
import { CHeader } from "@components/header";
9+
import { Decl, DeclDoc } from "@components/decl-doc";
10+
import { Desc, DescList } from "@components/desc";
11+
import Missing from "@components/Missing.astro";
12+
import { ParamDoc, ParamDocList } from "@components/param-doc";
13+
import { Revision, RevisionBlock } from "@components/revision";
14+
15+
Defined in header <CHeader name="string" />.
16+
17+
<DeclDoc id={1}>
18+
<Decl slot="decl">
19+
<RevisionBlock until="C99" noborder>
20+
```c
21+
void* memcpy(void *dest, const void *src, size_t count);
22+
```
23+
</RevisionBlock>
24+
</Decl>
25+
<Decl slot="decl">
26+
<RevisionBlock since="C11" noborder>
27+
```c
28+
void* memcpy(void *restrict dest, const void *restrict src,
29+
size_t count);
30+
```
31+
</RevisionBlock>
32+
</Decl>
33+
34+
Copies `count` characters from the object pointed to by `src` to the object pointed to by `dest`. Both objects are interpreted as arrays of `unsigned char`.
35+
36+
The behavior is <Behavior kind="undef">undefined</Behavior> if access occurs beyond the end of the dest array. If the objects overlap <Revision since="C99">(which is a violation of the `restrict` contract)</Revision>, the behavior is <Behavior kind="undef">undefined</Behavior>. The behavior is <Behavior kind="undef">undefined</Behavior> if either dest or src is an invalid or null pointer.
37+
</DeclDoc>
38+
39+
<DeclDoc id={2}>
40+
<Decl slot="decl">
41+
<RevisionBlock since="C11" noborder>
42+
```c
43+
errno_t memcpy_s(void *restrict dest, rsize_t destsz,
44+
const void *restrict src, rsize_t count);
45+
```
46+
</RevisionBlock>
47+
</Decl>
48+
49+
Same as #1, except that the following errors are detected at runtime and cause the entire destination range `[dest, dest+destsz)` to be zeroed out (if both `dest` and `destsz` are valid), as well as call the currently installed <Missing>constraint handler</Missing> function:
50+
51+
- `dest` or `src` is a null pointer
52+
- `destsz` or `count` is greater than `RSIZE_MAX`
53+
- `count` is greater than `destsz` (buffer overflow would occur)
54+
- the source and the destination objects overlap
55+
56+
The behavior is <Behavior kind="undef">undefined</Behavior> if the size of the character array pointed to by `dest` < `count` \<= `destsz`; in other words, an erroneous value of `destsz` does not expose the impending buffer overflow.
57+
58+
As with all bounds-checked functions, `memcpy_s` is only guaranteed to be available if `__STDC_LIB_EXT1__` is defined by the implementation and if the user defines `__STDC_WANT_LIB_EXT1__` to the integer constant `1` before including <CHeader name="string" />.
59+
</DeclDoc>
60+
61+
## Parameters
62+
63+
<ParamDocList>
64+
<ParamDoc name="dest">
65+
pointer to the object to copy to
66+
</ParamDoc>
67+
<ParamDoc name="destsz">
68+
max number of bytes to modify in the destination (typically the size of the destination object)
69+
</ParamDoc>
70+
<ParamDoc name="src">
71+
pointer to the object to copy from
72+
</ParamDoc>
73+
<ParamDoc name="count">
74+
number of bytes to copy
75+
</ParamDoc>
76+
</ParamDocList>
77+
78+
## Return value
79+
80+
1. Returns a copy of `dest`
81+
2. Returns zero on success and non-zero value on error. Also on error, if `dest` is not a null pointer and `destsz` is valid, writes `destsz` zero bytes in to the destination array.
82+
83+
## Notes
84+
85+
`memcpy` may be used to set the <Missing>effective type</Missing> of an object obtained by an allocation function.
86+
87+
`memcpy` is the fastest library routine for memory-to-memory copy. It is usually more efficient than <Missing>`strcpy`</Missing>, which must scan the data it copies or <Missing>`memmove`</Missing>, which must take precautions to handle overlapping inputs.
88+
89+
Several C compilers transform suitable memory-copying loops to `memcpy` calls.
90+
91+
Where <Missing>strict aliasing</Missing> prohibits examining the same memory as values of two different types, `memcpy` may be used to convert the values.
92+
93+
## Example
94+
95+
```c
96+
#define __STDC_WANT_LIB_EXT1__ 1
97+
#include <stdio.h>
98+
#include <stdint.h>
99+
#include <inttypes.h>
100+
#include <string.h>
101+
#include <stdlib.h>
102+
103+
int main(void) {
104+
// simple usage
105+
char source[] = "once upon a midnight dreary...";
106+
char dest[4];
107+
memcpy(dest, source, sizeof(dest));
108+
for (size_t n = 0; n < sizeof(dest); ++n)
109+
putchar(dest[n]);
110+
111+
// setting effective type of allocated memory to be int
112+
int *p = malloc(3 * sizeof(int)); // allocated memory has no effective type
113+
int arr[3] = {1, 2, 3};
114+
memcpy(p, arr, 3 * sizeof(int)); // allocated memory now has an effective type
115+
116+
// reinterpreting data
117+
double d = 0.1;
118+
// int64_t n = *(int64_t *)(&d); // strict aliasing violation
119+
int64_t n;
120+
memcpy(&n, &d, sizeof d); // OK
121+
printf("\n%a is %" PRIx64 " as an int64_t\n", d, n);
122+
123+
#ifdef __STDC_LIB_EXT1__
124+
set_constraint_handler_s(ignore_handler_s);
125+
char src[] = "aaaaaaaaaa";
126+
char dst[] = "xyxyxyxyxy";
127+
int r = memcpy_s(dst, sizeof(dst), src, 5);
128+
printf("dst = \"%s\", r = %d\n", dst,r);
129+
r = memcpy_s(dst, 5, src, 10); // count is greater than destsz
130+
printf("dst = \"");
131+
for (size_t ndx = 0; ndx<sizeof(dst); ++ndx) {
132+
char c = dst[ndx];
133+
c ? printf("%c", c) : printf("\\0");
134+
}
135+
printf("\", r = %d\n", r);
136+
#endif
137+
}
138+
```
139+
140+
Possible output:
141+
142+
```
143+
once
144+
0x1.999999999999ap-4 is 3fb999999999999a as an int64_t
145+
dst = "aaaaayxyxy", r = 0
146+
dst = "\0\0\0\0\0yxyxy", r = 22
147+
```
148+
149+
## References
150+
151+
- C11 standard (ISO/IEC 9899:2011):
152+
- 7.24.2.1 The memcpy function (p: 362)
153+
- K.3.7.1.1 The memcpy_s function (p: 614)
154+
- C99 standard (ISO/IEC 9899:1999):
155+
- 7.21.2.1 The memcpy function (p: 325)
156+
- C89/C90 standard (ISO/IEC 9899:1990):
157+
- 4.11.2.1 The memcpy function

‎src/content/docs/cpp/language/basic/main_function.mdx‎

Lines changed: 14 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ cppdoc:
77
import Code from "@astrojs/starlight/components";
88

99
import Behavior from "@components/Behavior.astro";
10-
import DeclDoc from "@components/DeclDoc.astro";
10+
import { Decl, DeclDoc } from "@components/decl-doc";
1111
import { DR, DRList } from "@components/defect-report";
1212
import Missing from "@components/Missing.astro";
1313
import { ParamDoc, ParamDocList } from "@components/param-doc";
@@ -17,38 +17,35 @@ import WG21PaperLink from "@components/WG21PaperLink.astro";
1717
A program shall contain a global namespace function named `main`, which is the designated start of the program in hosted environment. It shall have one of the following forms:
1818

1919
<DeclDoc>
20-
<Fragment slot="decl">
20+
<Decl slot="decl">
2121
```cpp
2222
int main() { /* body */ }
2323
```
24-
</Fragment>
25-
<Fragment slot="doc">
26-
A `main` function running independently of environment-provided arguments.
27-
</Fragment>
24+
</Decl>
25+
26+
A `main` function running independently of environment-provided arguments.
2827
</DeclDoc>
2928

3029
<DeclDoc>
31-
<Fragment slot="decl">
30+
<Decl slot="decl">
3231
```cpp
3332
int main(int argc, char *argv[]) { /* body */ }
3433
```
35-
</Fragment>
36-
<Fragment slot="doc">
37-
A `main` function accepting environment-provided arguments.
34+
</Decl>
35+
36+
A `main` function accepting environment-provided arguments.
3837

39-
The names of `argc` and `argv` are arbitrary, as well as the representation of the types of the parameters: `int main(int ac, char** av)` is equally valid.
40-
</Fragment>
38+
The names of `argc` and `argv` are arbitrary, as well as the representation of the types of the parameters: `int main(int ac, char** av)` is equally valid.
4139
</DeclDoc>
4240

4341
<DeclDoc>
44-
<Fragment slot="decl">
42+
<Decl slot="decl">
4543
```cpp
4644
int main(/* implementation-defined */) { /* body */ }
4745
```
48-
</Fragment>
49-
<Fragment slot="doc">
50-
A main function of implement-defined type, returning `int`.
51-
</Fragment>
46+
</Decl>
47+
48+
A main function of implement-defined type, returning `int`.
5249
</DeclDoc>
5350

5451
The C++ standard recommends implementation-defined main functions to place the extra (optional) parameters after `argv`.

‎src/styles/custom.css‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@
1313
--cppdoc-color-undef: var(--sl-color-red);
1414
--cppdoc-color-ill-formed: var(--sl-color-red);
1515
--cppdoc-color-ifndr: var(--sl-color-red);
16+
17+
--sl-sidebar-width: 22rem;
1618
}
1719

1820
.sl-markdown-content code {

0 commit comments

Comments
 (0)