]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
5b85fb0e | 2 | .\" Copyright 2022 Alejandro Colomar <alx@kernel.org> |
fea681da | 3 | .\" |
5b85fb0e | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da | 5 | .\" |
4c1c5274 | 6 | .TH stpncpy 3 (date) "Linux man-pages (unreleased)" |
fea681da | 7 | .SH NAME |
5b85fb0e AC |
8 | stpncpy, strncpy |
9 | \- zero a fixed-width buffer and | |
10 | copy a string into a character sequence with truncation | |
11 | and zero the rest of it | |
5a517def AC |
12 | .SH LIBRARY |
13 | Standard C library | |
8fc3b2cf | 14 | .RI ( libc ", " \-lc ) |
fea681da MK |
15 | .SH SYNOPSIS |
16 | .nf | |
fea681da | 17 | .B #include <string.h> |
68e4db0a | 18 | .PP |
4131356c | 19 | .BI "char *strncpy(char " dst "[restrict ." sz "], \ |
5b85fb0e AC |
20 | const char *restrict " src , |
21 | .BI " size_t " sz ); | |
4131356c | 22 | .BI "char *stpncpy(char " dst "[restrict ." sz "], \ |
5b85fb0e AC |
23 | const char *restrict " src , |
24 | .BI " size_t " sz ); | |
fea681da | 25 | .fi |
68e4db0a | 26 | .PP |
d39ad78f | 27 | .RS -4 |
79247bb1 MK |
28 | Feature Test Macro Requirements for glibc (see |
29 | .BR feature_test_macros (7)): | |
d39ad78f | 30 | .RE |
68e4db0a | 31 | .PP |
79247bb1 | 32 | .BR stpncpy (): |
9d2adbae MK |
33 | .nf |
34 | Since glibc 2.10: | |
5c10d2c5 | 35 | _POSIX_C_SOURCE >= 200809L |
9d2adbae MK |
36 | Before glibc 2.10: |
37 | _GNU_SOURCE | |
38 | .fi | |
fea681da | 39 | .SH DESCRIPTION |
5b85fb0e | 40 | These functions copy the string pointed to by |
2d251a70 | 41 | .I src |
5b85fb0e AC |
42 | into a null-padded character sequence at the fixed-width buffer pointed to by |
43 | .IR dst . | |
44 | If the destination buffer, | |
45 | limited by its size, | |
46 | isn't large enough to hold the copy, | |
47 | the resulting character sequence is truncated. | |
48 | For the difference between the two functions, see RETURN VALUE. | |
fea681da | 49 | .PP |
5b85fb0e | 50 | An implementation of these functions might be: |
fea681da | 51 | .PP |
2d251a70 AC |
52 | .in +4n |
53 | .EX | |
54 | char * | |
4131356c | 55 | strncpy(char *restrict dst, const char *restrict src, size_t sz) |
2d251a70 | 56 | { |
4131356c AC |
57 | stpncpy(dst, src, sz); |
58 | return dst; | |
5b85fb0e | 59 | } |
fe5dba13 | 60 | \& |
5b85fb0e | 61 | char * |
4131356c | 62 | stpncpy(char *restrict dst, const char *restrict src, size_t sz) |
5b85fb0e | 63 | { |
4131356c AC |
64 | bzero(dst, sz); |
65 | return mempcpy(dst, src, strnlen(src, sz)); | |
2d251a70 AC |
66 | } |
67 | .EE | |
68 | .in | |
47297adb | 69 | .SH RETURN VALUE |
5b85fb0e | 70 | .TP |
5b85fb0e AC |
71 | .BR strncpy () |
72 | returns | |
73 | .IR dst . | |
4131356c AC |
74 | .TP |
75 | .BR stpncpy () | |
76 | returns a pointer to | |
77 | one after the last character in the destination character sequence. | |
f27f40b7 | 78 | .SH ATTRIBUTES |
ea1e1b75 PH |
79 | For an explanation of the terms used in this section, see |
80 | .BR attributes (7). | |
81 | .TS | |
82 | allbox; | |
c466875e | 83 | lbx lb lb |
ea1e1b75 PH |
84 | l l l. |
85 | Interface Attribute Value | |
86 | T{ | |
9e54434e BR |
87 | .na |
88 | .nh | |
5b85fb0e AC |
89 | .BR stpncpy (), |
90 | .BR strncpy () | |
ea1e1b75 PH |
91 | T} Thread safety MT-Safe |
92 | .TE | |
c466875e | 93 | .sp 1 |
3113c7f3 | 94 | .SH STANDARDS |
5b85fb0e | 95 | .TP |
4131356c AC |
96 | .BR strncpy () |
97 | C11, POSIX.1-2008. | |
98 | .TP | |
5b85fb0e AC |
99 | .BR stpncpy () |
100 | POSIX.1-2008. | |
4131356c | 101 | .SH STANDARDS |
5b85fb0e AC |
102 | .TP |
103 | .BR strncpy () | |
4131356c AC |
104 | C89, POSIX.1-2001, SVr4, 4.3BSD. |
105 | .TP | |
106 | .BR stpncpy () | |
107 | glibc 1.07. | |
108 | POSIX.1-2008. | |
5b85fb0e AC |
109 | .SH CAVEATS |
110 | The name of these functions is confusing. | |
111 | These functions produce a null-padded character sequence, | |
112 | not a string (see | |
113 | .BR string_copying (7)). | |
114 | .PP | |
115 | It's impossible to distinguish truncation by the result of the call, | |
116 | from a character sequence that just fits the destination buffer; | |
117 | truncation should be detected by | |
118 | comparing the length of the input string | |
119 | with the size of the destination buffer. | |
120 | .PP | |
121 | If you're going to use this function in chained calls, | |
122 | it would be useful to develop a similar function that accepts | |
123 | a pointer to the end (one after the last element) of the destination buffer | |
124 | instead of its size. | |
125 | .SH EXAMPLES | |
126 | .\" SRC BEGIN (stpncpy.c) | |
127 | .EX | |
128 | #include <err.h> | |
129 | #include <stdio.h> | |
130 | #include <stdlib.h> | |
131 | #include <string.h> | |
fe5dba13 | 132 | \& |
5b85fb0e AC |
133 | int |
134 | main(void) | |
135 | { | |
136 | char *p; | |
137 | char buf1[20]; | |
138 | char buf2[20]; | |
139 | size_t len; | |
fe5dba13 | 140 | \& |
5b85fb0e AC |
141 | if (sizeof(buf2) < strlen("Hello world!")) |
142 | warnx("strncpy: truncating character sequence"); | |
e3c1c813 | 143 | strncpy(buf2, "Hello world!", sizeof(buf2)); |
5b85fb0e | 144 | len = strnlen(buf2, sizeof(buf2)); |
fe5dba13 | 145 | \& |
5b85fb0e AC |
146 | printf("[len = %zu]: ", len); |
147 | printf("%.*s\en", (int) len, buf2); // "Hello world!" | |
fe5dba13 | 148 | \& |
4131356c AC |
149 | if (sizeof(buf1) < strlen("Hello world!")) |
150 | warnx("stpncpy: truncating character sequence"); | |
151 | p = stpncpy(buf1, "Hello world!", sizeof(buf1)); | |
152 | len = p \- buf1; | |
fe5dba13 | 153 | \& |
4131356c AC |
154 | printf("[len = %zu]: ", len); |
155 | printf("%.*s\en", (int) len, buf1); // "Hello world!" | |
fe5dba13 | 156 | \& |
5b85fb0e AC |
157 | exit(EXIT_SUCCESS); |
158 | } | |
159 | .EE | |
160 | .\" SRC END | |
47297adb | 161 | .SH SEE ALSO |
5b85fb0e AC |
162 | .BR wcpncpy (3), |
163 | .BR string_copying (7) |