The OpenNET Project / Index page

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

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

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

fn_searchlist_destroy (3)
  • >> fn_searchlist_destroy (3) ( Solaris man: Библиотечные вызовы )
  • 
    NAME
         fn_attr_search,     FN_searchlist_t,     fn_searchlist_next,
         fn_searchlist_destroy  -  search  for  the  atomic  name  of
         objects with the specified attributes in a single context
    
    SYNOPSIS
         #include <xfn/xfn.h>
    
         FN_searchlist_t   *fn_attr_search(FN_ctx_t    *ctx,    const
         FN_composite_name_t  *name, const FN_attrset_t *match_attrs,
         unsigned     int     return_ref,     const      FN_attrset_t
         *return_attr_ids, FN_status_t *status);
    
         FN_string_t     *fn_searchlist_next(FN_searchlist_t     *sl,
         FN_ref_t   **returned_ref,   FN_attrset_t  **returned_attrs,
         FN_status_t *status);
    
         void fn_searchlist_destroy(FN_searchlist_t *sl);
    
    DESCRIPTION
         This set of operations is used to enumerate names of objects
         bound  in the target context named name relative to the con-
         text ctx with attributes whose values match all those speci-
         fied by match_attrs.
    
         The attributes specified by  match_attrs form a  conjunctive
         AND  expression  against  which the attributes of each named
         object in the target context are evaluated. For multi-valued
         attributes,  the  list order of values is ignored and attri-
         bute values not specified in match_attrs are ignored. If  no
         value  is  specified  for  an  attribute in match_attrs, the
         presence of  the  attribute  is  tested.  If  the  value  of
         match_attrs  is  0,  all  names  in  the  target context are
         enumerated.
    
         If  a  non-zero   value   of   return_ref   is   passed   to
         fn_attr_search(),   the  reference  bound  to  the  name  is
         returned     in     the     returned_ref     argument     to
         fn_searchlist_next().
    
         Attribute  identifiers  and  values  associated  with  named
         objects   that   satisfy  match_attrs  may  be  returned  by
         fn_searchlist_next().  The  attributes  returned  are  those
         listed  in the return_attr_ids argument to fn_attr_search().
         If the value of return_attr_ids is  0,  all  attributes  are
         returned.  If return_attr_ids is an empty FN_attrset_t(3XFN)
         object, no attributes are returned. Any attribute values  in
         return_attr_ids  are ignored; only the attribute identifiers
         are relevant for  return_attr_ids.
    
         The call to  fn_attr_search() initiates the enumeration pro-
         cess.  It returns a handle to an FN_searchlist_t object that
         is used to enumerate the names of the objects  whose  attri-
         butes match the attributes specified by match_attrs.
    
         The operation fn_searchlist_next() returns the next name  in
         the  enumeration  identified by the sl. The reference of the
         name is returned in returned_ref if return_ref  was  set  in
         the  call  to  fn_attr_search(). The attributes specified by
         return_attr_ids    are    returned    in     returned_attrs.
         fn_searchlist_next()  also  updates sl to indicate the state
         of the enumeration. Successive calls to fn_searchlist_next()
         using sl return successive names, and optionally, references
         and attributes, in  the  enumeration;  these  calls  further
         update the state of the enumeration.
    
         fn_searchlist_destroy() releases resources used  during  the
         enumeration.  This  can  be invoked at any time to terminate
         the enumeration.
    
         fn_attr_search() does not follow XFN links that are bound in
         the target context.
    
    RETURN VALUES
         fn_attr_search() returns a  pointer  to  an  FN_searchlist_t
         object  if  the  enumeration  is  successfully initiated; it
         returns a NULL pointer if the  enumeration  cannot  be  ini-
         tiated  or  if  no named object with attributes whose values
         match those specified in match_attrs is found.
    
         fn_searchlist_next()    returns    a    pointer    to     an
         FN_string_t(3XFN)  object;  it  returns a NULL pointer if no
         more  names  can  be  returned  in   the   enumeration.   If
         returned_ref is a NULL pointer, or if the return_ref parame-
         ter to fn_attr_search was 0, no reference is returned;  oth-
         erwise,  returned_ref  contains  the  reference bound to the
         name. If returned_attrs is a NULL pointer, no attributes are
         returned; otherwise,  returned_attrs contains the attributes
         associated with  the  named  object,  as  specified  by  the
         return_attr_ids parameter to fn_attr_search().
    
         In the case of a failure, these  operations  return  in  the
         status argument a code indicating the nature of the failure.
    
    ERRORS
         fn_attr_search() returns a NULL pointer if  the  enumeration
         could  not  be  initiated. The status argument is set in the
         following way:
    
         FN_SUCCESS
               A named object could not  be  found  whose  attributes
               satisfied  the implied filter of equality and conjunc-
               tion.
    
         FN_E_ATTR_NO_PERMISSION
               The caller did not have permission to read one or more
               of the specified attributes.
    
         FN_E_INVALID_ATTR_VALUE
               A value type in the specified attributes did not match
               the syntax of the attribute against which it was being
               evaluated.
    
         Other  status   codes   are   possible   as   described   in
         FN_status_t(3XFN) and xfn_status_codes(3XFN).
    
         Each successful call to fn_searchlist_next() returns a  name
         and,  optionally,  the  reference  and requested attributes.
         status is set in the following way:
    
         FN_SUCCESS
               All requested attributes  were  returned  successfully
               with the name.
    
         FN_E_ATTR_NO_PERMISSION
               The caller did not have permission to read one or more
               of the requested attributes.
    
         FN_E_INVALID_ATTR_IDENTIFIER
               A requested attribute identifier was not in  a  format
               acceptable  to  the naming system, or its contents was
               not valid for the format specified.
    
         FN_E_NO_SUCH_ATTRIBUTE
               The named object did not have  one  of  the  requested
               attributes.
    
         FN_E_INSUFFICIENT_RESOURCES
               Insufficient resources are available to return all the
               requested attributes and their values.
    
         FN_E_ATTR_NO_PERMISSION
    
         FN_E_INVALID_ATTR_IDENTIFIER
    
         FN_E_NO_SUCH_ATTRIBUTE
    
         FN_E_INSUFFICIENT_RESOURCES
               These indicate that some of the  requested  attributes
               may  have  been  returned in returned_attrs but one or
               more   of   them   could   not   be   returned.    Use
               fn_attr_get(3XFN)  or  fn_attr_multi_get(3XFN) to dis-
               cover why these attributes could not be returned.
    
         fn_searchlist_next() returns a NULL pointer if no more names
         can be returned. The status argument is set in the following
         way:
    
         FN_SUCCESS
               The search has completed successfully.
    
         FN_E_PARTIAL_RESULT
               The enumeration is not yet complete but cannot be con-
               tinued.
    
         FN_E_ATTR_NO_PERMISSION
               The caller did not have permission to read one or more
               of the specified attributes.
    
         FN_E_INVALID_ENUM_HANDLE
               The supplied enumeration handle was not valid.  Possi-
               ble  reasons could be that the handle was from another
               enumeration, or the context being enumerated no longer
               accepts  the  handle  (due  to  such  events as handle
               expiration or updates to the context).
    
         Other  status   codes   are   possible   as   described   in
         FN_status_t(3XFN) and xfn_status_codes(3XFN).
    
    USAGE
         The names  enumerated  using  fn_searchlist_next()  are  not
         ordered  in any way. Furthermore, there is no guarantee that
         any two series of enumerations  on  the  same  context  with
         identical  match_attrs  will  return  the  names in the same
         order.
    
    EXAMPLES
         Example 1:  A  sample  program  of  displaying  how  to  use
         fn_attr_search() function.
    
         The   following   code   fragment   illustrates   how    the
         fn_attr_search() operation may be used. The code consists of
         three parts:  preparing the arguments for the  search,  per-
         forming the search, and cleaning up.
    
         The first part involves getting the name of the  context  to
         start the search and constructing the set of attributes that
         named objects in the context must satisfy. This is  done  in
         the  declarations  part  of  the  code  and  by  the routine
         get_search_query.
    
         The next part involves doing the search and enumerating  the
         results  of the search. This is done by first getting a con-
         text handle to the Initial Context, and  then  passing  that
         handle  along with the name of the target context and match-
         ing attributes to fn_attr_search(). This particular call  to
         fn_attr_search() is requesting that no reference be returned
         (by passing in 0 for return_ref), and  that  all  attributes
         associated  with the named object be returned (by passing in
         0  as  the   return_attr_ids   argument).   If   successful,
         fn_attr_search()  returns  sl,  a handle for enumerating the
         results of  the  search.  The  results  of  the  search  are
         enumerated   using   calls  to  fn_searchlist_next(),  which
         returns the name of the object and the attributes associated
         with the named object in returned_attrs.
    
         The last part of the code involves cleaning up the resources
         used   during  the  search  and  enumeration.  The  call  to
         fn_searchlist_destroy() releases resources reserved for this
         enumeration.   The  other  calls release the context handle,
         name, attribute set, and status objects created earlier.
    
         /* Declarations */
         FN_ctx_t *ctx;
         FN_searchlist_t *sl;
         FN_string_t *name;
         FN_attrset_t *returned_attrs;
         FN_status_t *status = fn_status_create();
         FN_composite_name_t *target_name = get_name_from_user_input();
         FN_attrset_t *match_attrs = get_search_query();
         /* Get context handle to Initial Context */
         ctx = fn_ctx_handle_from_initial(status);
         /* error checking on 'status' */
         /* Initiate search */
         if ((sl=fn_attr_search(ctx, target_name, match_attrs,
              /* no reference */ 0, /* return all attrs */ 0, status)) == 0) {
              /* report 'status', cleanup, and exit */
         }
         /* Enumerate names and attributes requested */
         while (name=fn_searchlist_next(sl, 0, &returned_attrs, status)) {
              /* do something with 'name' and 'returned_attrs'*/
              fn_string_destroy(name);
              fn_attrset_destroy(returned_attrs);
         }
         /* check 'status' for reason for end of enumeration */
         /* Clean up */
         fn_searchlist_destroy(sl); /* Free resources of 'sl' */
         fn_status_destroy(status);
         fn_attrset_destroy(match_attrs);
         fn_ctx_handle_destroy(ctx);
         fn_composite_name_destroy(target_name);
         /*
          * Procedure for constructing attribute set containing
          * attributes to be matched:
          *   "zip_code" attribute value is "02158"
          *   AND "employed" attribute is present.
         */
         FN_attrset_t *
         get_search_query()
         {
              /* Zip code and employed attribute identifier, syntax */
              extern FN_attribute_t          *attr_zip_code;
              extern FN_attribute_t          *attr_employed;
              FN_attribute_t *zip_code = fn_attribute_copy(attr_zip_code);
              FN_attr_value_t zc_value = {5, "02158"};
              FN_attrset_t *match_attrs = fn_attrset_create();
              fn_attribute_add(zip_code, &zc_value, 0);
              fn_attrset_add(match_attrs, zip_code, 0);
              fn_attrset_add(match_attrs, attr_employed, 0);
              return (match_attrs);
         }
    
    ATTRIBUTES
         See attributes(5) for descriptions of the  following  attri-
         butes:
    
         ____________________________________________________________
        |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
        |_____________________________|_____________________________|
        | MT-Level                    | MT-Safe                     |
        |_____________________________|_____________________________|
    
    
    SEE ALSO
         FN_attribute_t(3XFN),                    FN_attrset_t(3XFN),
         FN_attrvalue_t(3XFN),             FN_composite_name_t(3XFN),
         FN_ctx_t(3XFN),    FN_status_t(3XFN),     FN_string_t(3XFN),
         fn_attr_ext_search(3XFN),                 fn_attr_get(3XFN),
         fn_attr_multi_get(3XFN),            fn_ctx_list_names(3XFN),
         xfn_status_codes(3XFN), attributes(5)
    
    
    
    


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




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

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