freebsd-skq/lib/libc/string/ffs.3

.\" Copyright (c) 1990, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek.
.\" 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. 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.
.\"
.\"     @(#)ffs.3	8.2 (Berkeley) 4/19/94
.\" $FreeBSD$
.\"
.Dd September 29, 2012
.Dt FFS 3
.Os
.Sh NAME
.Nm ffs ,
.Nm ffsl ,
.Nm ffsll ,
.Nm fls ,
.Nm flsl ,
.Nm flsll
.Nd find first or last bit set in a bit string
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In strings.h
.Ft int
.Fn ffs "int value"
.Ft int
.Fn ffsl "long value"
.Ft int
.Fn ffsll "long long value"
.Ft int
.Fn fls "int value"
.Ft int
.Fn flsl "long value"
.Ft int
.Fn flsll "long long value"
.Sh DESCRIPTION
The
.Fn ffs ,
.Fn ffsl
and
.Fn ffsll
functions find the first (least significant) bit set
in
.Fa value
and return the index of that bit.
.Pp
The
.Fn fls ,
.Fn flsl
and
.Fn flsll
functions find the last (most significant) bit set in
.Fa value
and return the index of that bit.
.Pp
Bits are numbered starting at 1, the least significant bit.
A return value of zero from any of these functions means that the
argument was zero.
.Sh SEE ALSO
.Xr bitstring 3
.Sh HISTORY
The
.Fn ffs
function appeared in
.Bx 4.3 .
Its prototype existed previously in
.In string.h
before it was moved to
.In strings.h
for
.St -p1003.1-2001
compliance.
.Pp
The
.Fn ffsl ,
.Fn fls
and
.Fn flsl
functions appeared in
.Fx 5.3 .
The
.Fn ffsll
and
.Fn flsll
functions appeared in
.Fx 7.1 .
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.\" Copyright (c) 1990, 1991, 1993`
			`.\" The Regents of the University of California. All rights reserved.`
			`.\"`
			`.\" This code is derived from software contributed to Berkeley by`
			`.\" Chris Torek.`
			`.\" 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.`
Renumber clauses to reduce diffs to other versions NetBSD, OpenBSD, and Android's Bionic number the clauses 1 through 3, so follow suit to make comparison easier. 2013-05-28 20:57:40 +00:00			`.\" 3. Neither the name of the University nor the names of its contributors`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.\" 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.`
			`.\"`
			`.\" @(#)ffs.3 8.2 (Berkeley) 4/19/94`
$Id$ -> $FreeBSD$ 1999-08-28 00:22:10 +00:00			`.\" $FreeBSD$`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.\"`
clarify the wording for 'first' and 'last' Approved by: wblock MFC after: 3 days 2012-09-30 03:25:04 +00:00			`.Dd September 29, 2012`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Dt FFS 3`
			`.Os`
			`.Sh NAME`
Add and document ffsl(), fls() and flsl(). 2004-01-13 16:05:47 +00:00			`.Nm ffs ,`
			`.Nm ffsl ,`
Add the ffsll and flsll functions. These are ffs and fls operating on long long arguments. Reviewed by: bde (previous version, that included asm implementation for all ffs and fls functions on i386 and amd64) MFC after: 2 weeks 2008-11-03 10:22:19 +00:00			`.Nm ffsll ,`
Add and document ffsl(), fls() and flsl(). 2004-01-13 16:05:47 +00:00			`.Nm fls ,`
Add the ffsll and flsll functions. These are ffs and fls operating on long long arguments. Reviewed by: bde (previous version, that included asm implementation for all ffs and fls functions on i386 and amd64) MFC after: 2 weeks 2008-11-03 10:22:19 +00:00			`.Nm flsl ,`
			`.Nm flsll`
Add and document ffsl(), fls() and flsl(). 2004-01-13 16:05:47 +00:00			`.Nd find first or last bit set in a bit string`
Introduce ".Lb" macro to libc manpages. More libraries manpages updates following. 2000-04-21 09:42:15 +00:00			`.Sh LIBRARY`
			`.Lb libc`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Sh SYNOPSIS`
- Update the manual page to show that the associated header file is <strings.h> and not <string.h> anymore. - Tell the reader about this change in the HISTORY section. - Switch to use an ANSI-C function definition. - Include <strings.h> instead of <string.h> in the source file. 2002-08-30 19:08:53 +00:00			`.In strings.h`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Ft int`
			`.Fn ffs "int value"`
Add and document ffsl(), fls() and flsl(). 2004-01-13 16:05:47 +00:00			`.Ft int`
			`.Fn ffsl "long value"`
			`.Ft int`
Add the ffsll and flsll functions. These are ffs and fls operating on long long arguments. Reviewed by: bde (previous version, that included asm implementation for all ffs and fls functions on i386 and amd64) MFC after: 2 weeks 2008-11-03 10:22:19 +00:00			`.Fn ffsll "long long value"`
Fix prototype for ffsll(3) and fls(3). PR: docs/156796 Submitted by: Jean-Yves Migeon <jeanyves.migeon free.fr> MFC after: 3 days 2011-05-03 19:33:06 +00:00			`.Ft int`
Add and document ffsl(), fls() and flsl(). 2004-01-13 16:05:47 +00:00			`.Fn fls "int value"`
			`.Ft int`
			`.Fn flsl "long value"`
Add the ffsll and flsll functions. These are ffs and fls operating on long long arguments. Reviewed by: bde (previous version, that included asm implementation for all ffs and fls functions on i386 and amd64) MFC after: 2 weeks 2008-11-03 10:22:19 +00:00			`.Ft int`
			`.Fn flsll "long long value"`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Sh DESCRIPTION`
			`The`
Add the ffsll and flsll functions. These are ffs and fls operating on long long arguments. Reviewed by: bde (previous version, that included asm implementation for all ffs and fls functions on i386 and amd64) MFC after: 2 weeks 2008-11-03 10:22:19 +00:00			`.Fn ffs ,`
Add and document ffsl(), fls() and flsl(). 2004-01-13 16:05:47 +00:00			`.Fn ffsl`
Add the ffsll and flsll functions. These are ffs and fls operating on long long arguments. Reviewed by: bde (previous version, that included asm implementation for all ffs and fls functions on i386 and amd64) MFC after: 2 weeks 2008-11-03 10:22:19 +00:00			`and`
			`.Fn ffsll`
clarify the wording for 'first' and 'last' Approved by: wblock MFC after: 3 days 2012-09-30 03:25:04 +00:00			`functions find the first (least significant) bit set`
Don't say "rightmost" when referring to the least significant bit. PR: docs/94803 MFC after: 3 days 2006-10-12 15:08:41 +00:00			`in`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Fa value`
Add and document ffsl(), fls() and flsl(). 2004-01-13 16:05:47 +00:00			`and return the index of that bit.`
			`.Pp`
			`The`
Add the ffsll and flsll functions. These are ffs and fls operating on long long arguments. Reviewed by: bde (previous version, that included asm implementation for all ffs and fls functions on i386 and amd64) MFC after: 2 weeks 2008-11-03 10:22:19 +00:00			`.Fn fls ,`
Add and document ffsl(), fls() and flsl(). 2004-01-13 16:05:47 +00:00			`.Fn flsl`
Add the ffsll and flsll functions. These are ffs and fls operating on long long arguments. Reviewed by: bde (previous version, that included asm implementation for all ffs and fls functions on i386 and amd64) MFC after: 2 weeks 2008-11-03 10:22:19 +00:00			`and`
			`.Fn flsll`
clarify the wording for 'first' and 'last' Approved by: wblock MFC after: 3 days 2012-09-30 03:25:04 +00:00			`functions find the last (most significant) bit set in`
Add and document ffsl(), fls() and flsl(). 2004-01-13 16:05:47 +00:00			`.Fa value`
			`and return the index of that bit.`
			`.Pp`
clarify the wording for 'first' and 'last' Approved by: wblock MFC after: 3 days 2012-09-30 03:25:04 +00:00			`Bits are numbered starting at 1, the least significant bit.`
Add and document ffsl(), fls() and flsl(). 2004-01-13 16:05:47 +00:00			`A return value of zero from any of these functions means that the`
			`argument was zero.`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Sh SEE ALSO`
			`.Xr bitstring 3`
			`.Sh HISTORY`
			`The`
			`.Fn ffs`
			`function appeared in`
			`.Bx 4.3 .`
- Update the manual page to show that the associated header file is <strings.h> and not <string.h> anymore. - Tell the reader about this change in the HISTORY section. - Switch to use an ANSI-C function definition. - Include <strings.h> instead of <string.h> in the source file. 2002-08-30 19:08:53 +00:00			`Its prototype existed previously in`
mdoc(7): Use the new feature of the .In macro. 2003-09-08 19:57:22 +00:00			`.In string.h`
- Update the manual page to show that the associated header file is <strings.h> and not <string.h> anymore. - Tell the reader about this change in the HISTORY section. - Switch to use an ANSI-C function definition. - Include <strings.h> instead of <string.h> in the source file. 2002-08-30 19:08:53 +00:00			`before it was moved to`
mdoc(7): Use the new feature of the .In macro. 2003-09-08 19:57:22 +00:00			`.In strings.h`
- Update the manual page to show that the associated header file is <strings.h> and not <string.h> anymore. - Tell the reader about this change in the HISTORY section. - Switch to use an ANSI-C function definition. - Include <strings.h> instead of <string.h> in the source file. 2002-08-30 19:08:53 +00:00			`for`
			`.St -p1003.1-2001`
			`compliance.`
Add and document ffsl(), fls() and flsl(). 2004-01-13 16:05:47 +00:00			`.Pp`
			`The`
			`.Fn ffsl ,`
			`.Fn fls`
			`and`
			`.Fn flsl`
			`functions appeared in`
			`.Fx 5.3 .`
Add the ffsll and flsll functions. These are ffs and fls operating on long long arguments. Reviewed by: bde (previous version, that included asm implementation for all ffs and fls functions on i386 and amd64) MFC after: 2 weeks 2008-11-03 10:22:19 +00:00			`The`
			`.Fn ffsll`
			`and`
			`.Fn flsll`
			`functions appeared in`
Document that ffsll(3) and flsll(3) functions first appeared in FreeBSD 7.1 Submitted by: Jan Henrik Sylvester <me janh de> MFC after: 3 days 2009-01-13 13:19:42 +00:00			`.Fx 7.1 .`