The OpenNET Project / Index page

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

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

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

fn_ctx_list_names (3)
  • >> fn_ctx_list_names (3) ( Solaris man: Библиотечные вызовы )
  • 
    NAME
         fn_ctx_list_names,     FN_namelist_t,      fn_namelist_next,
         fn_namelist_destroy  - list the atomic names bound in a con-
         text
    
    SYNOPSIS
         cc [ flag ... ] file ... -lxfn [ library ... ]
         #include <xfn/xfn.h>
    
         FN_namelist_t   *fn_ctx_list_names(FN_ctx_t   *ctx,    const
         FN_composite_name_t *name, FN_status_t *status);
    
         FN_string_t *fn_namelist_next(FN_namelist_t *nl, FN_status_t
         *status);
    
         void  fn_namelist_destroy(FN_namelist_t   *nl,   FN_status_t
         *status);
    
    DESCRIPTION
         This set of operations is used to list the  names  bound  in
         the target context named  name relative to the context  ctx.
         Note that  name must name a context. If  the  intent  is  to
         list  the contents of ctx, name should be an empty composite
         name.
    
         The call to  fn_ctx_list_names() initiates  the  enumeration
         process. It returns a handle to an FN_namelist_t object that
         can be used to enumerate the names in the target context.
    
         The operation  fn_namelist_next() returns the next  name  in
         the  enumeration identified by nl and updates nl to indicate
         the  state  of  the  enumeration.    Successive   calls   to
         fn_namelist_next()  using  nl return successive names in the
         enumeration and further update the state of the enumeration.
         fn_namelist_next()  returns  a  NULL  pointer  (0)  when the
         enumeration has been completed.
    
         fn_namelist_destroy() is used to release resources used dur-
         ing the enumeration. This may be invoked at any time to ter-
         minate the enumeration.
    
    RETURN VALUES
         fn_ctx_list_names() returns a pointer  to  an  FN_namelist_t
         object  if the enumeration is successfully initiated; other-
         wise it returns a NULL pointer (0).
    
         fn_namelist_next() returns a NULL pointer  (0)  if  no  more
         names can be returned in the enumeration.
    
         In the case of a failure, these operations return in  status
         a code indicating the nature of the failure.
    
    ERRORS
         Each successful call to  fn_namelist_next() returns  a  name
         and sets status to FN_SUCCESS.
    
         When  fn_namelist_next() returns  a  NULL  pointer  (0),  it
         indicates  that no more names can be returned. status is set
         in the following way:
    
         FN_SUCCESS
               The enumeration has completed successfully.
    
         FN_E_INVALID_ENUM_HANDLE
               The supplied enumeration handle is not valid. Possible
               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).
    
         FN_E_PARTIAL_RESULT
               The enumeration is not yet complete but cannot be con-
               tinued.
    
         Other status codes, such as FN_E_COMMUNICATION_FAILURE,  are
         also    possible    in    calls    to   fn_ctx_list_names(),
         fn_namelist_next(), and  fn_namelist_destroy(). These  func-
         tions  set  status for these other status codes as described
         in FN_status_t(3XFN) and xfn_status_codes(3XFN).
    
    USAGE
         The  names  enumerated  using  fn_namelist_next()  are   not
         ordered in any way.  There is no guaranteed relation between
         the order in which names are added  to  a  context  and  the
         order  of  names  obtained by enumeration. The specification
         does  not guarantee that any two series of enumerations will
         return the names in the same order.
    
         When a name is added to or removed from a context, this  may
         or  may  not   invalidate  the  enumeration  handle that the
         client holds for that context.  If  the  enumeration  handle
         becomes invalid, the status code FN_E_INVALID_ENUM_HANDLE is
         returned in   status.  If  the  enumeration  handle  remains
         valid,  the update may or may not be visible to the client.
    
         In addition, there may be a  relationship  between  the  ctx
         argument    supplied    to   fn_ctx_list_names()   and   the
         FN_namelist_t object it returns.  For example,  some  imple-
         mentations  may  store  the  context  handle  ctx within the
         FN_namelist_t  object  for   subsequent   fn_namelist_next()
         calls.  In general, a fn_ctx_handle_destroy(3XFN) should not
         be invoked on ctx until the enumeration has terminated.
    
    
    EXAMPLES
         Example 1: A sample program.
    
         The following code fragment illustrates how the  list  names
         operations may be used:
    
         extern FN_string_t *user_input;
         FN_ctx_t *ctx;
         FN_composite_name_t *target_name = fn_composite_name_from_string(user_input);
         FN_status_t *status = fn_status_create();
         FN_string_t *name;
         FN_namelist_t *nl;
         ctx = fn_ctx_handle_from_initial(status);
         /* error checking on 'status' */
         if ((nl=fn_ctx_list_names(ctx, target_name, status)) == 0) {
              /* report 'status' and exit */
         }
         while (name=fn_namelist_next(nl, status)) {
              /* do something with 'name' */
              fn_string_destroy(name);
         }
         /* check 'status' for reason for end of enumeration and report if necessary */
         /* clean up */
         fn_namelist_destroy(nl, status);
         /* report 'status' */
    
    ATTRIBUTES
         See attributes(5) for descriptions of the  following  attri-
         butes:
    
         ____________________________________________________________
        |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
        |_____________________________|_____________________________|
        | MT-Level                    | MT-Safe                     |
        |_____________________________|_____________________________|
    
    
    SEE ALSO
         FN_composite_name_t(3XFN),                   FN_ctx_t(3XFN),
         FN_status_t(3XFN),                        FN_string_t(3XFN),
         fn_ctx_handle_destroy(3XFN),                      xfn(3XFN),
         xfn_status_codes(3XFN), attributes(5)
    
    NOTES
         The implementation of XFN in this Solaris release  is  based
         on  the  X/Open preliminary specification. It is likely that
         there will be minor changes to these interfaces  to  reflect
         changes in the final version of this specification. The next
         minor release of Solaris will offer binary compatibility for
         applications  developed using the current interfaces. As the
         interfaces evolve toward  standardization,  it  is  possible
         that  future  releases  of Solaris will require minor source
         code  changes  to  applications  that  have  been  developed
         against the preliminary specification.
    
    
    
    


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




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

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