.if n .pH ddi.rm/d3/gen/phalloc @(#)phalloc	43.11 of 12/5/92
.\" Copyright 1991, 1992 UNIX System Laboratories, Inc.
.\" Copyright 1989 AT&T
.TH phalloc D3
.IX "\f4phalloc\fP(D3)"
.SH NAME
\f4phalloc\f1 \- allocate and initialize a pollhead structure
.SH SYNOPSIS
.nf
.na
.ft 4
#include <sys/poll.h>
#include <sys/kmem.h>
#include <sys/ddi.h>
.sp 0.4
struct pollhead *phalloc(int \f2flag\fP);
.ft 1
.ad
.fi
.SS Arguments
.RS 0
.IP "\f2flag\f1" 10n
Specifies whether the caller is willing to sleep
waiting for memory.
.RE
.SH DESCRIPTION
\f4phalloc\f1 allocates and initializes a \f4pollhead\f1
structure for use by non-STREAMS character drivers that wish to
support polling.
If \f2flag\f1 is set to \f4KM_SLEEP\f1, the caller will sleep if
necessary until sufficient memory is available.
If \f2flag\f1 is set to \f4KM_NOSLEEP\f1, the caller will not sleep,
but \f4phalloc\fP will return \f4NULL\f1 if sufficient memory is not immediately
available.
.SS "Return Values"
On success, \f4phalloc\f1 returns a pointer to the newly
allocated \f4pollhead\f1 structure.
If \f4KM_NOSLEEP\f1 is specified and sufficient memory is not immediately
available, \f4phalloc\f1 returns a \f4NULL\f1 pointer.
.SH USAGE
On systems where the \f4phalloc\fP function is available,
DDI/DKI conforming drivers should only use \f4pollhead\f1 structures which
have been allocated and initialized using \f4phalloc\f1.
Use of \f4pollhead\f1 structures which have been obtained by any other means
is prohibited on such systems.
.SS Level
Base only if \f2flag\f1 is set to \f4KM_SLEEP\f1.
.P
Initialization, Base or Interrupt if \f2flag\f1 is set to \f4KM_NOSLEEP\f1.
.SS "Synchronization Constraints"
May sleep if flag is set to \f4KM_SLEEP\f1.
.P
Driver-defined basic locks and read/write locks may
be held across calls to this function if \f2flag\f1 is \f4KM_NOSLEEP\f1
but may not be held if \f2flag\f1 is \f4KM_SLEEP\f1.
.P
Driver-defined sleep locks may be held
across calls to this function regardless of the value of \f2flag\f1.
.SH REFERENCES
.na
\f4poll\fP(D2),
\f4phfree\fP(D3)
.ad