The OpenNET Project / Index page

[ новости /+++ | форум | теги | ]

Интерактивная система просмотра системных руководств (man-ов)

 ТемаНаборКатегория 
 
 [Cписок руководств | Печать]

nvlist_alloc (9)
  • nvlist_alloc (3) ( Solaris man: Библиотечные вызовы )
  • >> nvlist_alloc (9) ( Solaris man: Ядро )
  •  

    NAME

    nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack, nvlist_unpack, nvlist_dup, nv_alloc_init, nv_alloc_fini, nvlist_xalloc, nvlist_xpack, nvlist_xunpack, nvlist_xdup, nvlist_merge - Manage a name-value pair list
     
    

    SYNOPSIS

    #include <sys/nvpair.h> 
    
    List Manipulation:
    
    int nvlist_alloc(nvlist_t **nvlp, uint_t nvflag,
        int kmflag);
    

    int nvlist_xalloc(nvlist_t **nvlp, uint_t nvflag, nv_alloc_t *nva);
    

    void nvlist_free(nvlist_t *nvl);
    

    int nvlist_size(nvlist_t *nvl, size_t *size, int encoding);
    

    int nvlist_pack(nvlist_t *nvl, char **bufp, size_t *buflen, int encoding,
        int flag);
    

    int nvlist_xpack(nvlist_t *nvl, char **bufp, size_t *buflen, int encoding,
        nv_alloc_t *nva);
    

    int nvlist_unpack(char *buf, size_t buflen, nvlist_t **nvlp, int flag);
    

    int nvlist_xunpack(char *buf, size_t buflen, nvlist_t **nvlp, 
        nv_alloc_t *nva);
    

    int nvlist_dup(nvlist_t *nvl, nvlist_t **nvlp, int flag);
    

    int nvlist_xdup(nvlist_t *nvl, nvlist_t **nvlp, nv_alloc_t *nva);
    

    int nvlist_merge(nvlist_t *dst, nvlist_t *nvl, int flag);
    

    Pluggable Allocator Configuration:
    
    nv_alloc_t *nvlist_lookup_nv_alloc(nvlist_t *);
    

    int nv_alloc_init(nv_alloc_t *nva, 
        const nv_alloc_ops_t * nvo,/* args */ ...);
    

    void  nv_alloc_reset(nv_alloc_t  *nva);
    

    void  nv_alloc_fini(nv_alloc_t *nva);
    

    Pluggable Allocation Initialization with Fixed Allocator:
    
    int nv_alloc_init(nv_alloc_t *nva,
        nv_fixed_ops, void * bufptr,  size_t sz);
    

     

    INTERFACE LEVEL

    Solaris DDI specific (Solaris DDI)  

    PARAMETERS

    nvlp

    Address of a pointer to list of name-value pairs (nvlist_t).

    nvflag

    Specify bit fields defining nvlist_t properties:

    NV_UNIQUE_NAME

    nvpair names are unique.

    NV_UNIQUE_NAME_TYPE

    Name-data type combination is unique

    kmflag

    Kernel memory allocation policy, either KM_SLEEP or KM_NOSLEEP.

    nvl

    nvlist_t to be processed.

    dst

    Destination nvlist_t.

    size

    Pointer to buffer to contain the encoded size.

    bufp

    Address of buffer to pack nvlist into. Must be 8-byte aligned. If NULL, library will allocate memory.

    buf

    Buffer containing packed nvlist_t.

    buflen

    Size of buffer bufp or buf points to.

    encoding

    Encoding method for packing.

    nvo

    Pluggable allocator operations pointer (nv_alloc_ops_t).

    nva

    Points to a nv_alloc_t structure to be used for the specified nvlist_t.

     

    DESCRIPTION

    List Manipulation:

    The nvlist_alloc() function allocates a new name-value pair list and updates nvlp to point to the handle. The argument nvflag specifies nvlist_t properties to remain persistent across packing, unpacking, and duplication.

    If NV_UNIQUE_NAME is specified for nvflag, existing nvpairs with matching names are removed before the new nvpair is added. If NV_UNIQUE_NAME_TYPE is specified for nvflag, existing nvpairs with matching names and data types are removed before the new nvpair is added. See nvlist_add_byte(9F) for more details.

    The nvlist_xalloc() function differs from nvlist_alloc() in that nvlist_xalloc() can use a different allocator, as described in the Pluggable Allocators section.

    The nvlist_free() function frees a name-value pair list.

    The nvlist_size() function returns the minimum size of a contiguous buffer large enough to pack nvl. The encoding parameter specifies the method of encoding when packing nvl. Supported encoding methods are:

    NV_ENCODE_NATIVE

    Straight bcopy() as described in bcopy(9F).

    NV_ENCODE_XDR

    Use XDR encoding, suitable for sending to another host.

    The nvlist_pack() function packs nvl into contiguous memory starting at *bufp. The encoding parameter specifies the method of encoding (see above).

    o If *bufp is not NULL, *bufp is expected to be a caller-allocated buffer of size *buflen. The kmflag argument is ignored.
    o If *bufp is NULL, the library allocates memory and updates *bufp to point to the memory and updates *buflen to contain the size of the allocated memory. The value of kmflag indicates the memory allocation policy

    The nvlist_xpack() function differs from nvlist_pack() in that nvlist_xpack() can use a different allocator.

    The nvlist_unpack() function takes a buffer with a packed nvlist_t and unpacks it into a searchable nvlist_t. The library allocates memory for nvlist_t. The caller is responsible for freeing the memory by calling nvlist_free().

    The nvlist_xunpack() function differs from nvlist_unpack() in that nvlist_xunpack() can use a different allocator.

    The nvlist_dup() function makes a copy of nvl and updates nvlp to point to the copy.

    The nvlist_xdup() function differs from nvlist_dup() in that nvlist_xdup() can use a different allocator.

    The nvlist_merge() function adds copies of all name-value pairs from nvlist_t nvl to nvlist_t dst. Name-value pairs in dst are replaced with name-value pairs from nvl which have identical names (if dst has the type NV_UNIQUE_NAME), or identical names and types (if dst has the type NV_UNIQUE_NAME_TYPE).

    The nvlist_lookup_nv_alloc() function retrieves the pointer to the allocator used when manipulating a name-value pair list.  

    PLUGGABLE ALLOCATORS

    Using Pluggable Allocators:

    The nv_alloc_init(), nv_alloc_reset() and nv_alloc_fini() functions provide an interface that specifies the allocator to be used when manipulating a name-value pair list.

    The nv_alloc_init() determines allocator properties and puts them into the nva argument. You need to specify the nv_arg argument, the nvo argument and an optional variable argument list. The optional arguments are passed to the (*nv_ao_init()) function.

    The nva argument must be passed to nvlist_xalloc(), nvlist_xpack(), nvlist_xunpack() and nvlist_xdup().

    The nv_alloc_reset() function resets the allocator properties to the data specified by nv_alloc_init(). When no (*nv_ao_reset()) function is specified, nv_alloc_reset() is without effect.

    The nv_alloc_fini() destroys the allocator properties determined by nv_alloc_init(). When a (*nv_ao_fini()) routine is specified, it is called from nv_alloc_fini().

    The disposition of the allocated objects and the memory used to store them is left to the allocator implementation.

    The `nv_alloc_sleep' and `nv_alloc_nosleep' nv_alloc_t pointers may be used with nvlist_xalloc to mimic the behavior of nvlist_alloc with KM_SLEEP and KM_NOSLEEP, respectively.

    o  nv_alloc_nosleep
    o  nv_alloc_sleep
    

    The nvpair framework provides a fixed-buffer allocator, accessible via nv_fixed_ops.

    o  nv_fixed_ops
    

    Given a buffer size and address, the fixed-buffer allocator allows for the creation of nvlists in contexts where malloc or kmem_alloc services may not be available. The fixed-buffer allocator is designed primarily to support the creation of nvlists.

    Memory freed using nvlist_free(), pair-removal, or similar routines is not reclaimed.

    When used to initialize the fixed-buffer allocator, nv_alloc_init should be called as follows:

    int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
       void *bufptr, size_t sz);
    

    When invoked on a fixed-buffer, the nv_alloc_reset() function resets the fixed buffer and prepares it for re-use. The framework consumer is responsible for freeing the buffer passed to nv_alloc_init().  

    CREATING PLUGGABLE ALLOCATORS

    Any producer of name-value pairs may possibily specify his own allocator routines. You must provide the following pluggable allocator operations in the allocator implementation.

    int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist);
    void (*nv_ao_fini)(nv_alloc_t *nva);
    void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz);
    void (*nv_ao_reset)(nv_alloc_t *nva);
    void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz);
    

    The nva argument of the allocator implementation is always the first argument.

    The optional (*nv_ao_init() ) function is responsible for filling the data specified by nv_alloc_init() into the nva_arg() argument. The (*nv_ao_init()) function is called only when nv_alloc_init() is executed.

    The optional (*nv_ao_fini()) function is responsible for the cleanup of the allocator implementation. It is called by nv_alloc_fini().

    The required (*nv_ao_alloc()) function is used in the nvpair allocation framework for memory allocation. The sz argument specifies the size of the requested buffer.

    The optional (*nv_ao_reset()) function is responsible for resetting the nva_arg argument to the data specified by nv_alloc_init().

    The required (*nv_ao_free()) function is used in the nvpair allocator framework for memory de-allocation. The argument buf is a pointer to a block previously allocated by (*nv_ao_alloc()) function. The size argument sz must exactly match the original allocation.

    The disposition of the allocated objects and the memory used to store them is left to the allocator implementation.  

    RETURN VALUES

    For nvlist_alloc(), nvlist_dup(), nvlist_xalloc(), and nvlist_xdup():

    0

    success

    EINVAL

    invalid argument

    ENOMEM

    insufficient memory

    For nvlist_pack(), nvlist_unpack(), nvlist_xpack(), and nvlist_xunpack():

    0

    success

    EINVAL

    invalid argument

    ENOMEM

    insufficient memory

    EFAULT

    encode/decode error

    ENOTSUP

    encode/decode method not supported

    For nvlist_size():

    0

    success

    EINVAL

    invalid argument

    For nvlist_lookup_nv_alloc():

    pointer to the allocator  

    USAGE

    The fixed-buffer allocator is very simple allocator. It uses a pre-allocated buffer for memory allocations and it can be used in interrupt context. You are responsible for allocation and de-allocation for the pre-allocated buffer.  

    EXAMPLES

      /*
      * using the fixed-buffer allocator.
      */
      #include <sys/nvpair.h>
         
     /* initialize the nvpair allocator framework */
     static nv_alloc_t *
     init(char *buf, size_t size)
     {
          nv_alloc_t *nvap;
    
          if ((nvap = kmem_alloc(sizeof(nv_alloc_t), KM_SLEEP)) == NULL)
              return (NULL);
    
          if (nv_alloc_init(nvap, nv_fixed_ops, buf, size) == 0)
              return (nvap);
    
          return (NULL);
      }
    
      static void
      fini(nv_alloc_t *nvap)
      {
            nv_alloc_fini(nvap);
            kmem_free(nvap, sizeof(nv_alloc_t));
      } 
       static int
       interrupt_context(nv_alloc_t *nva)
       {
          nvlist_t *nvl;
          int error;
    
          if ((error = nvlist_xalloc(&nvl, NV_UNIQUE_NAME, nva)) != 0)
               return (-1);
    
          if ((error = nvlist_add_int32(nvl, "name", 1234)) == 0)
               error = send_nvl(nvl);
         
          nvlist_free(nvl); 
          return (error);
         }
    

     

    CONTEXT

    The nvlist_alloc(), nvlist_pack(), nvlist_unpack(), and nvlist_dup() functions can be called from interrupt context only if the KM_NOSLEEP flag is set. They can be called from user context with any valid flag.

    The nvlist_xalloc(), nvlist_xpack(), nvlist_xunpack(), and nvlist_xdup() functions can be called from interrupt context only if (1) the default allocator is used and the KM_NOSLEEP flag is set or (2) the specified allocator did not sleep for free memory (for example, it uses a pre-allocated buffer for memory allocations).

    These functions can be called from user or kernel context with any valid flag.


     

    Index

    NAME
    SYNOPSIS
    INTERFACE LEVEL
    PARAMETERS
    DESCRIPTION
    PLUGGABLE ALLOCATORS
    CREATING PLUGGABLE ALLOCATORS
    RETURN VALUES
    USAGE
    EXAMPLES
    CONTEXT


    Поиск по тексту MAN-ов: 




    Партнёры:
    PostgresPro
    Inferno Solutions
    Hosting by Hoster.ru
    Хостинг:

    Закладки на сайте
    Проследить за страницей
    Created 1996-2024 by Maxim Chirkov
    Добавить, Поддержать, Вебмастеру