mirror of
https://gitlab.freedesktop.org/libbsd/libbsd.git
synced 2025-01-09 03:08:38 +01:00
Added manpages and fixed fmtcheck
This commit is contained in:
Aurelien Jarno
Guillem Jover
parent
91473e2748
commit
dedb8169c4
@ -1,7 +1,8 @@
|
||||
2005-12-18 Aurelien Jarno <aurel32@debian.org>
|
||||
2005-12-19 Aurelien Jarno <aurel32@debian.org>
|
||||
|
||||
* Added manpages
|
||||
* fmtcheck.c: new
|
||||
* include/string.h: added fmtcheck
|
||||
* include/stdlib.h: added fmtcheck
|
||||
* Versions: added fmtcheck
|
||||
|
||||
2005-11-01 Guillem Jover <guillem@debian.org>
|
||||
|
||||
8
Makefile
8
Makefile
@ -6,7 +6,9 @@
|
||||
|
||||
LIB_SRCS = arc4random.c fgetln.c inet_net_pton.c strlcat.c strlcpy.c md5c.c fmtcheck.c
|
||||
|
||||
LIB_INCLUDES = bsd.h md5.h
|
||||
LIB_INCLUDES = include/bsd/ip_icmp.h include/bsd/random.h include/bsd/queue.h include/bsd/md5.h include/bsd/string.h include/bsd/bsd.h include/bsd/stdlib.h
|
||||
|
||||
LIB_MANS = man/arc4random.3 man/strlcpy.3 man/fgetln.3 man/fmtcheck.3
|
||||
|
||||
LIB_STATIC_OBJS = $(LIB_SRCS:%.c=%.o)
|
||||
LIB_SHARED_OBJS = $(LIB_SRCS:%.c=%.lo)
|
||||
@ -49,11 +51,11 @@ $(LIB_SHARED): $(LIB_SHARED_OBJS)
|
||||
install: libs
|
||||
mkdir -p $(DESTDIR)/usr/lib/
|
||||
mkdir -p $(DESTDIR)/usr/include/bsd/
|
||||
mkdir -p $(DESTDIR)/usr/share/man/man3
|
||||
install -m644 $(LIB_STATIC) $(DESTDIR)/usr/lib/
|
||||
#install -m644 $(LIB_SONAME) $(DESTDIR)/usr/lib/
|
||||
install -m644 $(LIB_SHARED) $(DESTDIR)/usr/lib/
|
||||
#install -m644 $(LIB_SHARED_SO) $(DESTDIR)/usr/lib/
|
||||
install -m644 $(LIB_INCLUDES) $(DESTDIR)/usr/include/bsd/
|
||||
install -m644 $(LIB_MANS $(DESTDIR)/usr/share/man/man3)
|
||||
cd $(DESTDIR)/usr/lib/ ; ln -fs $(LIB_SHARED) $(LIB_SHARED_SO)
|
||||
cd $(DESTDIR)/usr/lib/ ; ln -fs $(LIB_SHARED) $(LIB_SONAME)
|
||||
|
||||
|
||||
1
Versions
1
Versions
@ -2,6 +2,7 @@ LIBBSD_0.0 {
|
||||
global:
|
||||
arc4random;
|
||||
fgetln;
|
||||
fgetwln;
|
||||
fmtcheck;
|
||||
inet_net_pton;
|
||||
strlcpy;
|
||||
|
||||
9
include/bsd/stdlib.h
Normal file
9
include/bsd/stdlib.h
Normal file
@ -0,0 +1,9 @@
|
||||
#ifndef LIBBSD_STDLIB_H
|
||||
#define LIBBSD_STDLIB_H
|
||||
|
||||
#include <sys/types.h>
|
||||
#include <stdio.h>
|
||||
|
||||
const char *fmtcheck(const char *, const char *);
|
||||
|
||||
#endif
|
||||
@ -7,6 +7,6 @@
|
||||
size_t strlcpy(char *dst, const char *src, size_t siz);
|
||||
size_t strlcat(char *dst, const char *src, size_t siz);
|
||||
char *fgetln(FILE *fp, size_t *lenp);
|
||||
const char *fmtcheck(const char *, const char *);
|
||||
wchar_t *fgetwln(FILE * __restrict fp, size_t *lenp);
|
||||
|
||||
#endif
|
||||
|
||||
107
man/arc4random.3
Normal file
107
man/arc4random.3
Normal file
@ -0,0 +1,107 @@
|
||||
.\" $OpenBSD: arc4random.3,v 1.2 1997/04/27 22:40:25 angelos Exp $
|
||||
.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\" 3. All advertising materials mentioning features or use of this software
|
||||
.\" must display the following acknowledgement:
|
||||
.\" This product includes software developed by Niels Provos.
|
||||
.\" 4. The name of the author may not be used to endorse or promote products
|
||||
.\" derived from this software without specific prior written permission.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
||||
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||||
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
||||
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
||||
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
||||
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
||||
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" Manual page, using -mandoc macros
|
||||
.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/gen/arc4random.3,v 1.16 2003/07/31 06:18:24 das Exp $
|
||||
.\"
|
||||
.Dd April 15, 1997
|
||||
.Dt ARC4RANDOM 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm arc4random ,
|
||||
.Nm arc4random_stir ,
|
||||
.Nm arc4random_addrandom
|
||||
.Nd arc4 random number generator
|
||||
.Sh LIBRARY
|
||||
.Lb libc
|
||||
.Sh SYNOPSIS
|
||||
.In stdlib.h
|
||||
.Ft u_int32_t
|
||||
.Fn arc4random "void"
|
||||
.Ft void
|
||||
.Fn arc4random_stir "void"
|
||||
.Ft void
|
||||
.Fn arc4random_addrandom "unsigned char *dat" "int datlen"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn arc4random
|
||||
function uses the key stream generator employed by the
|
||||
arc4 cipher, which uses 8*8 8 bit S-Boxes.
|
||||
The S-Boxes
|
||||
can be in about
|
||||
.if t 2\u\s71700\s10\d
|
||||
.if n (2**1700)
|
||||
states.
|
||||
The
|
||||
.Fn arc4random
|
||||
function returns pseudo-random numbers in the range of 0 to
|
||||
.if t 2\u\s731\s10\d\(mi1,
|
||||
.if n (2**32)\(mi1,
|
||||
and therefore has twice the range of
|
||||
.Xr rand 3
|
||||
and
|
||||
.Xr random 3 .
|
||||
.Pp
|
||||
The
|
||||
.Fn arc4random_stir
|
||||
function reads data from
|
||||
.Pa /dev/urandom
|
||||
and uses it to permute the S-Boxes via
|
||||
.Fn arc4random_addrandom .
|
||||
.Pp
|
||||
There is no need to call
|
||||
.Fn arc4random_stir
|
||||
before using
|
||||
.Fn arc4random ,
|
||||
since
|
||||
.Fn arc4random
|
||||
automatically initializes itself.
|
||||
.Sh EXAMPLES
|
||||
The following produces a drop-in replacement for the traditional
|
||||
.Fn rand
|
||||
and
|
||||
.Fn random
|
||||
functions using
|
||||
.Fn arc4random :
|
||||
.Pp
|
||||
.Dl "#define foo4random() (arc4random() % ((unsigned)RAND_MAX + 1))"
|
||||
.Sh SEE ALSO
|
||||
.Xr rand 3 ,
|
||||
.Xr random 3 ,
|
||||
.Xr srandomdev 3
|
||||
.Sh HISTORY
|
||||
.Pa RC4
|
||||
has been designed by RSA Data Security, Inc.
|
||||
It was posted anonymously
|
||||
to the USENET and was confirmed to be equivalent by several sources who
|
||||
had access to the original cipher.
|
||||
Since
|
||||
.Pa RC4
|
||||
used to be a trade secret, the cipher is now referred to as
|
||||
.Pa ARC4 .
|
||||
128
man/fgetln.3
Normal file
128
man/fgetln.3
Normal file
@ -0,0 +1,128 @@
|
||||
.\" Copyright (c) 1990, 1991, 1993
|
||||
.\" The Regents of the University of California. All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\" 3. All advertising materials mentioning features or use of this software
|
||||
.\" must display the following acknowledgement:
|
||||
.\" This product includes software developed by the University of
|
||||
.\" California, Berkeley and its contributors.
|
||||
.\" 4. Neither the name of the University nor the names of its contributors
|
||||
.\" may be used to endorse or promote products derived from this software
|
||||
.\" without specific prior written permission.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.\" @(#)fgetln.3 8.3 (Berkeley) 4/19/94
|
||||
.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/stdio/fgetln.3,v 1.8 2004/07/16 06:07:12 tjr Exp $
|
||||
.\"
|
||||
.Dd April 19, 1994
|
||||
.Dt FGETLN 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm fgetln
|
||||
.Nd get a line from a stream
|
||||
.Sh LIBRARY
|
||||
.Lb libc
|
||||
.Sh SYNOPSIS
|
||||
.In stdio.h
|
||||
.Ft char *
|
||||
.Fn fgetln "FILE *stream" "size_t *len"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn fgetln
|
||||
function
|
||||
returns a pointer to the next line from the stream referenced by
|
||||
.Fa stream .
|
||||
This line is
|
||||
.Em not
|
||||
a C string as it does not end with a terminating
|
||||
.Dv NUL
|
||||
character.
|
||||
The length of the line, including the final newline,
|
||||
is stored in the memory location to which
|
||||
.Fa len
|
||||
points.
|
||||
(Note, however, that if the line is the last
|
||||
in a file that does not end in a newline,
|
||||
the returned text will not contain a newline.)
|
||||
.Sh RETURN VALUES
|
||||
Upon successful completion a pointer is returned;
|
||||
this pointer becomes invalid after the next
|
||||
.Tn I/O
|
||||
operation on
|
||||
.Fa stream
|
||||
(whether successful or not)
|
||||
or as soon as the stream is closed.
|
||||
Otherwise,
|
||||
.Dv NULL
|
||||
is returned.
|
||||
The
|
||||
.Fn fgetln
|
||||
function
|
||||
does not distinguish between end-of-file and error; the routines
|
||||
.Xr feof 3
|
||||
and
|
||||
.Xr ferror 3
|
||||
must be used
|
||||
to determine which occurred.
|
||||
If an error occurs, the global variable
|
||||
.Va errno
|
||||
is set to indicate the error.
|
||||
The end-of-file condition is remembered, even on a terminal, and all
|
||||
subsequent attempts to read will return
|
||||
.Dv NULL
|
||||
until the condition is
|
||||
cleared with
|
||||
.Xr clearerr 3 .
|
||||
.Pp
|
||||
The text to which the returned pointer points may be modified,
|
||||
provided that no changes are made beyond the returned size.
|
||||
These changes are lost as soon as the pointer becomes invalid.
|
||||
.Sh ERRORS
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EBADF
|
||||
The argument
|
||||
.Fa stream
|
||||
is not a stream open for reading.
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fn fgetln
|
||||
function
|
||||
may also fail and set
|
||||
.Va errno
|
||||
for any of the errors specified for the routines
|
||||
.Xr fflush 3 ,
|
||||
.Xr malloc 3 ,
|
||||
.Xr read 2 ,
|
||||
.Xr stat 2 ,
|
||||
or
|
||||
.Xr realloc 3 .
|
||||
.Sh SEE ALSO
|
||||
.Xr ferror 3 ,
|
||||
.Xr fgets 3 ,
|
||||
.Xr fgetwln 3 ,
|
||||
.Xr fopen 3 ,
|
||||
.Xr putc 3
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Fn fgetln
|
||||
function first appeared in
|
||||
.Bx 4.4 .
|
||||
117
man/fmtcheck.3
Normal file
117
man/fmtcheck.3
Normal file
@ -0,0 +1,117 @@
|
||||
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" This file was contributed to The NetBSD Foundation by Allen Briggs.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\" 3. All advertising materials mentioning features or use of this software
|
||||
.\" must display the following acknowledgement:
|
||||
.\" This product includes software developed by the NetBSD
|
||||
.\" Foundation, Inc. and its contributors.
|
||||
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
||||
.\" contributors may be used to endorse or promote products derived
|
||||
.\" from this software without specific prior written permission.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
||||
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
||||
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
||||
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
||||
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
||||
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
||||
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
||||
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
||||
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
||||
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||||
.\" POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/gen/fmtcheck.3,v 1.9 2004/07/02 23:52:10 ru Exp $
|
||||
.Dd October 16, 2002
|
||||
.Os
|
||||
.Dt FMTCHECK 3
|
||||
.Sh NAME
|
||||
.Nm fmtcheck
|
||||
.Nd sanitizes user-supplied
|
||||
.Xr printf 3 Ns -style
|
||||
format string
|
||||
.Sh LIBRARY
|
||||
.Lb libc
|
||||
.Sh SYNOPSIS
|
||||
.In stdio.h
|
||||
.Ft const char *
|
||||
.Fn fmtcheck "const char *fmt_suspect" "const char *fmt_default"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn fmtcheck
|
||||
scans
|
||||
.Fa fmt_suspect
|
||||
and
|
||||
.Fa fmt_default
|
||||
to determine if
|
||||
.Fa fmt_suspect
|
||||
will consume the same argument types as
|
||||
.Fa fmt_default
|
||||
and to ensure that
|
||||
.Fa fmt_suspect
|
||||
is a valid format string.
|
||||
.Pp
|
||||
The
|
||||
.Xr printf 3
|
||||
family of functions cannot verify the types of arguments that they are
|
||||
passed at run-time.
|
||||
In some cases, like
|
||||
.Xr catgets 3 ,
|
||||
it is useful or necessary to use a user-supplied format string with no
|
||||
guarantee that the format string matches the specified arguments.
|
||||
.Pp
|
||||
The
|
||||
.Fn fmtcheck
|
||||
was designed to be used in these cases, as in:
|
||||
.Bd -literal -offset indent
|
||||
printf(fmtcheck(user_format, standard_format), arg1, arg2);
|
||||
.Ed
|
||||
.Pp
|
||||
In the check, field widths, fillers, precisions, etc.\& are ignored (unless
|
||||
the field width or precision is an asterisk
|
||||
.Ql *
|
||||
instead of a digit string).
|
||||
Also, any text other than the format specifiers
|
||||
is completely ignored.
|
||||
.Sh RETURN VALUES
|
||||
If
|
||||
.Fa fmt_suspect
|
||||
is a valid format and consumes the same argument types as
|
||||
.Fa fmt_default ,
|
||||
then the
|
||||
.Fn fmtcheck
|
||||
will return
|
||||
.Fa fmt_suspect .
|
||||
Otherwise, it will return
|
||||
.Fa fmt_default .
|
||||
.Sh SECURITY CONSIDERATIONS
|
||||
Note that the formats may be quite different as long as they accept the
|
||||
same arguments.
|
||||
For example,
|
||||
.Qq Li "%p %o %30s %#llx %-10.*e %n"
|
||||
is compatible with
|
||||
.Qq Li "This number %lu %d%% and string %s has %qd numbers and %.*g floats (%n)" .
|
||||
However,
|
||||
.Qq Li %o
|
||||
is not equivalent to
|
||||
.Qq Li %lx
|
||||
because
|
||||
the first requires an integer and the second requires a long.
|
||||
.Sh SEE ALSO
|
||||
.Xr printf 3
|
||||
.Sh BUGS
|
||||
The
|
||||
.Fn fmtcheck
|
||||
function does not understand all of the conversions that
|
||||
.Xr printf 3
|
||||
does.
|
||||
204
man/strlcpy.3
Normal file
204
man/strlcpy.3
Normal file
@ -0,0 +1,204 @@
|
||||
.\" $OpenBSD: strlcpy.3,v 1.5 1999/06/06 15:17:32 aaron Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 1998 Todd C. Miller <Todd.Miller@courtesan.com>
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\" 3. The name of the author may not be used to endorse or promote products
|
||||
.\" derived from this software without specific prior written permission.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
|
||||
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
|
||||
.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
|
||||
.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
||||
.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
||||
.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
|
||||
.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
|
||||
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
|
||||
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
|
||||
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/string/strlcpy.3,v 1.13 2004/07/02 23:52:13 ru Exp $
|
||||
.\"
|
||||
.Dd June 22, 1998
|
||||
.Dt STRLCPY 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm strlcpy ,
|
||||
.Nm strlcat
|
||||
.Nd size-bounded string copying and concatenation
|
||||
.Sh LIBRARY
|
||||
.Lb libc
|
||||
.Sh SYNOPSIS
|
||||
.In string.h
|
||||
.Ft size_t
|
||||
.Fn strlcpy "char *dst" "const char *src" "size_t size"
|
||||
.Ft size_t
|
||||
.Fn strlcat "char *dst" "const char *src" "size_t size"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn strlcpy
|
||||
and
|
||||
.Fn strlcat
|
||||
functions copy and concatenate strings respectively.
|
||||
They are designed
|
||||
to be safer, more consistent, and less error prone replacements for
|
||||
.Xr strncpy 3
|
||||
and
|
||||
.Xr strncat 3 .
|
||||
Unlike those functions,
|
||||
.Fn strlcpy
|
||||
and
|
||||
.Fn strlcat
|
||||
take the full size of the buffer (not just the length) and guarantee to
|
||||
NUL-terminate the result (as long as
|
||||
.Fa size
|
||||
is larger than 0 or, in the case of
|
||||
.Fn strlcat ,
|
||||
as long as there is at least one byte free in
|
||||
.Fa dst ) .
|
||||
Note that you should include a byte for the NUL in
|
||||
.Fa size .
|
||||
Also note that
|
||||
.Fn strlcpy
|
||||
and
|
||||
.Fn strlcat
|
||||
only operate on true
|
||||
.Dq C
|
||||
strings.
|
||||
This means that for
|
||||
.Fn strlcpy
|
||||
.Fa src
|
||||
must be NUL-terminated and for
|
||||
.Fn strlcat
|
||||
both
|
||||
.Fa src
|
||||
and
|
||||
.Fa dst
|
||||
must be NUL-terminated.
|
||||
.Pp
|
||||
The
|
||||
.Fn strlcpy
|
||||
function copies up to
|
||||
.Fa size
|
||||
- 1 characters from the NUL-terminated string
|
||||
.Fa src
|
||||
to
|
||||
.Fa dst ,
|
||||
NUL-terminating the result.
|
||||
.Pp
|
||||
The
|
||||
.Fn strlcat
|
||||
function appends the NUL-terminated string
|
||||
.Fa src
|
||||
to the end of
|
||||
.Fa dst .
|
||||
It will append at most
|
||||
.Fa size
|
||||
- strlen(dst) - 1 bytes, NUL-terminating the result.
|
||||
.Sh RETURN VALUES
|
||||
The
|
||||
.Fn strlcpy
|
||||
and
|
||||
.Fn strlcat
|
||||
functions return the total length of the string they tried to
|
||||
create.
|
||||
For
|
||||
.Fn strlcpy
|
||||
that means the length of
|
||||
.Fa src .
|
||||
For
|
||||
.Fn strlcat
|
||||
that means the initial length of
|
||||
.Fa dst
|
||||
plus
|
||||
the length of
|
||||
.Fa src .
|
||||
While this may seem somewhat confusing it was done to make
|
||||
truncation detection simple.
|
||||
.Pp
|
||||
Note however, that if
|
||||
.Fn strlcat
|
||||
traverses
|
||||
.Fa size
|
||||
characters without finding a NUL, the length of the string is considered
|
||||
to be
|
||||
.Fa size
|
||||
and the destination string will not be NUL-terminated (since there was
|
||||
no space for the NUL).
|
||||
This keeps
|
||||
.Fn strlcat
|
||||
from running off the end of a string.
|
||||
In practice this should not happen (as it means that either
|
||||
.Fa size
|
||||
is incorrect or that
|
||||
.Fa dst
|
||||
is not a proper
|
||||
.Dq C
|
||||
string).
|
||||
The check exists to prevent potential security problems in incorrect code.
|
||||
.Sh EXAMPLES
|
||||
The following code fragment illustrates the simple case:
|
||||
.Bd -literal -offset indent
|
||||
char *s, *p, buf[BUFSIZ];
|
||||
|
||||
\&...
|
||||
|
||||
(void)strlcpy(buf, s, sizeof(buf));
|
||||
(void)strlcat(buf, p, sizeof(buf));
|
||||
.Ed
|
||||
.Pp
|
||||
To detect truncation, perhaps while building a pathname, something
|
||||
like the following might be used:
|
||||
.Bd -literal -offset indent
|
||||
char *dir, *file, pname[MAXPATHLEN];
|
||||
|
||||
\&...
|
||||
|
||||
if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname))
|
||||
goto toolong;
|
||||
if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname))
|
||||
goto toolong;
|
||||
.Ed
|
||||
.Pp
|
||||
Since we know how many characters we copied the first time, we can
|
||||
speed things up a bit by using a copy instead of an append:
|
||||
.Bd -literal -offset indent
|
||||
char *dir, *file, pname[MAXPATHLEN];
|
||||
size_t n;
|
||||
|
||||
\&...
|
||||
|
||||
n = strlcpy(pname, dir, sizeof(pname));
|
||||
if (n >= sizeof(pname))
|
||||
goto toolong;
|
||||
if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n)
|
||||
goto toolong;
|
||||
.Ed
|
||||
.Pp
|
||||
However, one may question the validity of such optimizations, as they
|
||||
defeat the whole purpose of
|
||||
.Fn strlcpy
|
||||
and
|
||||
.Fn strlcat .
|
||||
As a matter of fact, the first version of this manual page got it wrong.
|
||||
.Sh SEE ALSO
|
||||
.Xr snprintf 3 ,
|
||||
.Xr strncat 3 ,
|
||||
.Xr strncpy 3
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Fn strlcpy
|
||||
and
|
||||
.Fn strlcat
|
||||
functions first appeared in
|
||||
.Ox 2.4 ,
|
||||
and made their appearance in
|
||||
.Fx 3.3 .
|
||||
Loading…
Reference in New Issue
Block a user