esballoc(9r) [osf1 man page]

esballoc(9r)															      esballoc(9r)

NAME

       esballoc - STREAMS: Allocates a message block with a shared buffer

SYNOPSIS

       #include <sys/stream.h>

       mblk_t * esballoc(
	       unsigned char *base,
	       int size,
	       int pri,
	       frtn_t *free_rtnp );

ARGUMENTS

       Specifies  the  address of the user-supplied data buffer.  Specifies the number of bytes in the data buffer.  Specifies the priority of the
       allocation request (to be used by the allocb interface, which esballoc calls).  Specifies the free interface (routine) data structure.

DESCRIPTION

       The esballoc interface creates a STREAMS message and attaches a user-supplied data buffer in place of a STREAMS data buffer.  The interface
       calls allocb to obtain a message and data block header. The user-supplied data buffer, pointed to by the base argument, is used as the data
       buffer for the message.

       The free_rtn structure is referenced by the dp_freep member of the datab structure.  When the freeb interface is called to  free  the  mes-
       sage, the driver's message free interface (referenced through the free_rtn structure) is called, with arguments, to free the data buffer.

       The free_rtn structure is defined as follows:

       /* Free return structure for esballoc */ typedef struct free_rtn {
	 void	 (*free_func)(char *, char *); /* Interface to free buffer */
	 char *  free_arg;		       /* Parameter to free_func */ } frtn_t;

       Instead	of  requiring  a specific number of arguments, the free_arg member is of type char *. This way, the driver can pass a pointer to a
       structure if more than one argument is needed.

NOTES

       The free_func interface must be defined in kernel space and should be declared void. It has no user context and must not sleep.

RETURN VALUES

       Upon successful completion, the esballoc interface returns a pointer to the newly allocated message block. This message block  is  of  type
       struct msgb *. The msgb data structure is defined in the /usr/sys/include/sys/stream.h file.

       On failure, esballoc returns a NULL pointer.

SEE ALSO

       Kernel Interfaces: allocb(9r), freeb(9r)

       Programmer's Guide: STREAMS

																      esballoc(9r)

esballoc(9F)						   Kernel Functions for Drivers 					      esballoc(9F)

NAME

       esballoc - allocate a message block using a caller-supplied buffer

SYNOPSIS

       #include <sys/stream.h>

       mblk_t *esballoc(uchar *base, size_t size, uint_t pri, frtn_t *fr_rtnp);

INTERFACE LEVEL

       Architecture independent level 1 (DDI/DKI).

PARAMETERS

       base	       Address of user supplied data buffer.

       size	       Number of bytes in data buffer.

       pri	       Priority of allocation request (to be used by  allocb(9F) function, called by  esballoc()).

       fr_rtnp	       Free routine data structure.

DESCRIPTION

       esballoc()  creates  a  STREAMS message and attaches a user-supplied data buffer in place of a STREAMS data buffer. It calls  allocb(9F) to
       get a message and data block header only. The newly allocated message will have both the b_wptr and b_rptr set to the base of  the  buffer.
       As  when  using allocb(9F), the	newly allocated message will have both b_wptr and b_rptr set to the base of the data buffer. The user-sup-
       plied data buffer, pointed to by  base, is used as the data buffer for the message.

       When  freeb(9F) is called to free the message, the driver's message freeing routine (referenced through the  free_rtn structure) is called,
       with appropriate arguments, to free the data buffer.

       The  free_rtn structure includes the following members:

	      void (*free_func)();     /* user's freeing routine */
	      char *free_arg;	       /* arguments to free_func() */

       Instead	of  requiring  a  specific  number  of	arguments, the	free_arg field is defined of type  char *. This way, the driver can pass a
       pointer to a structure if more than one argument is needed.

       The method by which free_func is called is implementation-specific. The module writer must not assume that free_func will or  will  not	be
       called directly from STREAMS utility routines like freeb(9F) which free a message block.

       free_func  must	not  call  another  modules put procedure nor attempt to acquire a private module lock which may be held by another thread
       across a call to a STREAMS utility routine which could free a message block. Otherwise, the possibility for lock recursion and/or  deadlock
       exists.

       free_func must not access any dynamically allocated data structure that might no longer exist when it runs.

RETURN VALUES

       On success, a pointer to the newly allocated message block is returned. On failure,  NULL is returned.

CONTEXT

       esballoc() can be called from user or interrupt context.

SEE ALSO

       allocb(9F), freeb(9F), datab(9S), free_rtn(9S)

       Writing Device Drivers STREAMS Programming Guide

WARNINGS

       The   free_func	must  be  defined  in kernel space, should be declared	void and accept one argument.  It has no user context and must not
       sleep.

SunOS 5.10							    23 Jun 1997 						      esballoc(9F)