Differential D27228 Diff 129461 lib/libc/string/strlcpy.3

Changeset View

Standalone View

lib/libc/string/strlcpy.3

	Show All 19 Lines
	.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,			.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
	.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,			.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
	.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;			.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
	.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,			.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
	.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR			.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
	.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF			.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
	.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.			.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	.\"			.\"
	.Dd May 1, 2020			.Dd October 27, 2023
	.Dt STRLCPY 3			.Dt STRLCPY 3
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm strlcpy ,			.Nm strlcpy ,
	.Nm strlcat			.Nm strlcat
	.Nd size-bounded string copying and concatenation			.Nd size-bounded string copying and concatenation
	.Sh LIBRARY			.Sh LIBRARY
	.Lb libc			.Lb libc
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In string.h			.In string.h
	.Ft size_t			.Ft size_t
	.Fn strlcpy "char * restrict dst" "const char * restrict src" "size_t dstsize"			.Fn strlcpy "char * restrict dst" "const char * restrict src" "size_t dstsize"
	.Ft size_t			.Ft size_t
	.Fn strlcat "char * restrict dst" "const char * restrict src" "size_t dstsize"			.Fn strlcat "char * restrict dst" "const char * restrict src" "size_t dstsize"
	.Sh DESCRIPTION			.Sh DESCRIPTION
	The			The
	.Fn strlcpy			.Fn strlcpy
	and			and
	.Fn strlcat			.Fn strlcat
	functions copy and concatenate strings with the			functions copy and concatenate strings with the same input parameters and output result as
	same input parameters and output result as			.Xr strcpy 3
	.Xr snprintf 3 .			and
				.Xr strcat 3
				with proper overflow protection.
	They are designed to be safer, more consistent, and less error			They are designed to be safer, more consistent, and less error
	prone replacements for the easily misused functions			prone replacements for the easily misused functions
	.Xr strncpy 3			.Xr strncpy 3
	and			and
	.Xr strncat 3 .			.Xr strncat 3 .
	.Pp			.Pp
	.Fn strlcpy			.Fn strlcpy
	and			and
	Show All 36 Lines
	is not a proper string).			is not a proper string).
	.Pp			.Pp
	If the			If the
	.Fa src			.Fa src
	and			and
	.Fa dst			.Fa dst
	strings overlap, the behavior is undefined.			strings overlap, the behavior is undefined.
	.Sh RETURN VALUES			.Sh RETURN VALUES
	Besides quibbles over the return type			The
	.Pf ( Va size_t
	versus
	.Va int )
	and signal handler safety
	.Pf ( Xr snprintf 3
	is not entirely safe on some systems), the
	following two are equivalent:
	.Bd -literal -offset indent
	n = strlcpy(dst, src, len);
	n = snprintf(dst, len, "%s", src);
	.Ed
	.Pp
	Like
	.Xr snprintf 3 ,
	the
	.Fn strlcpy			.Fn strlcpy
	and			and
	.Fn strlcat			.Fn strlcat
	functions return the total length of the string they tried to create.			functions return the total length of the string they tried to create.
	For			For
	.Fn strlcpy			.Fn strlcpy
	that means the length of			that means the length of
	.Fa src .			.Fa src .
	Show All 9 Lines
	.Cm >=			.Cm >=
	.Va dstsize ,			.Va dstsize ,
	the output string has been truncated.			the output string has been truncated.
	It is the caller's responsibility to handle this.			It is the caller's responsibility to handle this.
	.Sh EXAMPLES			.Sh EXAMPLES
	The following code fragment illustrates the simple case:			The following code fragment illustrates the simple case:
	.Bd -literal -offset indent			.Bd -literal -offset indent
	char s, p, buf[BUFSIZ];			char s, p, buf[BUFSIZ];

				scottlUnsubmitted Not Done Inline Actions I think it's essential to remove the passage in this section about strlcat and snprintf being equivalent. Otherwise you still have conflicting text, and now you've added even more conflicting and vague (the use of "some systems" here) text. Since the implementation of strlcat() is completely independent of snprintf(), nothing is gained by conveying or implying equivalence in the man page. scottl: I think it's essential to remove the passage in this section about strlcat and snprintf being…
	\&...			\&...

	(void)strlcpy(buf, s, sizeof(buf));			(void)strlcpy(buf, s, sizeof(buf));
	(void)strlcat(buf, p, sizeof(buf));			(void)strlcat(buf, p, sizeof(buf));
	.Ed			.Ed
	.Pp			.Pp
	To detect truncation, perhaps while building a pathname, something			To detect truncation, perhaps while building a pathname, something
	like the following might be used:			like the following might be used:
	▲ Show 20 Lines • Show All 55 Lines • Show Last 20 Lines