/share/man/man9/pbuf.9

  1.\"
  2.\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
  3.\"
  4.\" Redistribution and use in source and binary forms, with or without
  5.\" modification, are permitted provided that the following conditions
  6.\" are met:
  7.\" 1. Redistributions of source code must retain the above copyright
  8.\"    notice(s), this list of conditions and the following disclaimer as
  9.\"    the first lines of this file unmodified other than the possible
 10.\"    addition of one or more copyright notices.
 11.\" 2. Redistributions in binary form must reproduce the above copyright
 12.\"    notice(s), this list of conditions and the following disclaimer in the
 13.\"    documentation and/or other materials provided with the distribution.
 14.\"
 15.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
 16.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 17.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 18.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
 19.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 20.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 22.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 25.\" DAMAGE.
 26.\"
 27.\" $FreeBSD$
 28.\"
 29.Dd July 9, 2001
 30.Dt PBUF 9
 31.Os
 32.Sh NAME
 33.Nm pbuf ,
 34.Nm getpbuf ,
 35.Nm trypbuf ,
 36.Nm relpbuf
 37.Nd "functions for managing physical buffers"
 38.Sh SYNOPSIS
 39.In sys/param.h
 40.In sys/systm.h
 41.In sys/bio.h
 42.In sys/buf.h
 43.Ft "struct buf *"
 44.Fn getpbuf "int *pfreecnt"
 45.Ft "struct buf *"
 46.Fn trypbuf "int *pfreecnt"
 47.Ft void
 48.Fn relpbuf "struct buf *bp" "int *pfreecnt"
 49.Sh DESCRIPTION
 50These functions are used to allocate and release physical buffers.
 51.Pp
 52The physical buffers are allocated at system startup and are
 53maintained in a separate pool from the main system buffers.
 54They are intended for use by subsystems that cannot or should not be
 55reliant on the main pool of buffers (for example the swap pager).
 56The system allocates between 16 and 256 physical buffers depending
 57on the amount of memory in the system.
 58.Pp
 59Each subsystem that allocates buffers via these calls is expected
 60to manage its own percentage free counter.
 61If the value is initialized to \-1 the number of buffers available
 62to the subsystem is limited only by the number of physical buffers
 63available.
 64The number of buffers is stored in
 65.Va nswbuf
 66which is defined in
 67.In sys/buf.h
 68and initialized in
 69.Fn cpu_startup .
 70A recommended initialization value is 1/2
 71.Va nswbuf .
 72.Pp
 73The
 74.Fn getpbuf
 75function returns the first available buffer to the user.
 76If there are no buffers available,
 77.Fn getpbuf
 78will sleep waiting for one to become available.
 79If
 80.Fa pfreecnt
 81is zero,
 82.Fn getpbuf
 83will sleep until it increases.
 84.Fa pfreecnt
 85is decremented prior to returning.
 86.Pp
 87The
 88.Fn trypbuf
 89function returns the first available buffer.
 90If there are no buffers available,
 91.Dv NULL
 92is returned.
 93As well, if
 94.Fa pfreecnt
 95is zero,
 96.Dv NULL
 97is returned.
 98.Fa pfreecnt
 99is decremented prior to returning a valid buffer.
100If
101.Dv NULL
102is returned,
103.Fa pfreecnt
104is not modified.
105.Pp
106The
107.Fn relpbuf
108function releases the buffer back to the free list.
109If the buffers
110.Va b_rcred
111or
112.Va b_wcred
113structures are not
114.Dv NULL ,
115they are freed.
116See
117.Xr crfree 9 .
118.Pp
119.Fa pfreecnt
120is incremented prior to returning.
121.Sh RETURN VALUES
122.Fn getpbuf
123and
124.Fn trypbuf
125return a pointer to the buffer.
126In the case of
127.Fn trypbuf ,
128.Dv NULL
129can also be returned indicating that there are no buffers available.
130.Sh AUTHORS
131This manual page was written by
132.An Chad David Aq davidc@acns.ab.ca .