/share/man/man9/pbuf.9
https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 132 lines · 132 code · 0 blank · 0 comment · 0 complexity · 77aa076be2b1aeb4dbcaf295b84940ab MD5 · raw file
- .\"
- .\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. 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(s), this list of conditions and the following disclaimer as
- .\" the first lines of this file unmodified other than the possible
- .\" addition of one or more copyright notices.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice(s), this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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$
- .\"
- .Dd July 9, 2001
- .Dt PBUF 9
- .Os
- .Sh NAME
- .Nm pbuf ,
- .Nm getpbuf ,
- .Nm trypbuf ,
- .Nm relpbuf
- .Nd "functions for managing physical buffers"
- .Sh SYNOPSIS
- .In sys/param.h
- .In sys/systm.h
- .In sys/bio.h
- .In sys/buf.h
- .Ft "struct buf *"
- .Fn getpbuf "int *pfreecnt"
- .Ft "struct buf *"
- .Fn trypbuf "int *pfreecnt"
- .Ft void
- .Fn relpbuf "struct buf *bp" "int *pfreecnt"
- .Sh DESCRIPTION
- These functions are used to allocate and release physical buffers.
- .Pp
- The physical buffers are allocated at system startup and are
- maintained in a separate pool from the main system buffers.
- They are intended for use by subsystems that cannot or should not be
- reliant on the main pool of buffers (for example the swap pager).
- The system allocates between 16 and 256 physical buffers depending
- on the amount of memory in the system.
- .Pp
- Each subsystem that allocates buffers via these calls is expected
- to manage its own percentage free counter.
- If the value is initialized to \-1 the number of buffers available
- to the subsystem is limited only by the number of physical buffers
- available.
- The number of buffers is stored in
- .Va nswbuf
- which is defined in
- .In sys/buf.h
- and initialized in
- .Fn cpu_startup .
- A recommended initialization value is 1/2
- .Va nswbuf .
- .Pp
- The
- .Fn getpbuf
- function returns the first available buffer to the user.
- If there are no buffers available,
- .Fn getpbuf
- will sleep waiting for one to become available.
- If
- .Fa pfreecnt
- is zero,
- .Fn getpbuf
- will sleep until it increases.
- .Fa pfreecnt
- is decremented prior to returning.
- .Pp
- The
- .Fn trypbuf
- function returns the first available buffer.
- If there are no buffers available,
- .Dv NULL
- is returned.
- As well, if
- .Fa pfreecnt
- is zero,
- .Dv NULL
- is returned.
- .Fa pfreecnt
- is decremented prior to returning a valid buffer.
- If
- .Dv NULL
- is returned,
- .Fa pfreecnt
- is not modified.
- .Pp
- The
- .Fn relpbuf
- function releases the buffer back to the free list.
- If the buffers
- .Va b_rcred
- or
- .Va b_wcred
- structures are not
- .Dv NULL ,
- they are freed.
- See
- .Xr crfree 9 .
- .Pp
- .Fa pfreecnt
- is incremented prior to returning.
- .Sh RETURN VALUES
- .Fn getpbuf
- and
- .Fn trypbuf
- return a pointer to the buffer.
- In the case of
- .Fn trypbuf ,
- .Dv NULL
- can also be returned indicating that there are no buffers available.
- .Sh AUTHORS
- This manual page was written by
- .An Chad David Aq davidc@acns.ab.ca .