st_objlist_delete man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

st_objlist_append(3)					  st_objlist_append(3)

NAME
       st_objlist_append,	  st_objlist_delete,	     st_objlist_first,
       st_objlist_last,	 st_objlist_close,   st_foreach_obj,   st_addr_to_obj,
       st_file_to_obj,	  st_proc_to_obj,   st_sym_to_obj,   st_objlist_exter‐
       nal_name_sym - create, close, or perform operations on object lists

SYNOPSIS
       #include <st.h>

       st_status_t st_objlist_append(
	       st_objlist_t **obj_list,
	       st_obj_t *obj ); st_status_t st_objlist_delete(
	       st_objlist_t **obj_list,
	       st_obj_t *obj ); st_status_t st_objlist_close(
	       st_objlist_t *obj_list ); st_status_t st_objlist_first(
	       st_objlist_t *obj_list,
	       st_obj_t **obj ); st_status_t st_objlist_last(
	       st_objlist_t *obj_list,
	       st_obj_t **obj ); st_status_t st_addr_to_obj(
	       st_objlist_t *obj_list,
	       st_addr_t addr,
	       st_obj_t **result ); st_status_t st_file_to_obj
	       st_objlist_t *obj_list,
	       st_file_t file,
	       st_obj_t **result ); st_status_t st_proc_to_obj(
		st_objlist_t *obj_list,
	       st_proc_t proc,
	       st_obj_t **result ); st_status_t st_sym_to_obj(
	       st_objlist_t *obj_list,
	       st_sym_t sym,
	       st_obj_t **result ); st_status_t st_objlist_external_name_sym(
	       st_objlist_t *obj_list,
	       const char *name,
	       st_sym_t *sym ); st_status_t st_foreach_obj(
	       st_objlist_t *obj_list,
	       st_status_t  (*routine)	__((st_obj_t  *obj,   st_any_t	 data,
       st_any_t *retval)),
	       st_any_t data,
	       st_any_t *retval );

LIBRARY
       Symbol Table and Object File Access Library (libst.a)

PARAMETERS
       For the st_objlist_append() function, specifies an address to which the
       function returns a handle to the object list it creates or augments. To
       create  an object list, supply a pointer to NULL for this parameter and
       an object handle for the obj parameter.	To  append  an	object	to  an
       existing	 object list, supply the object list handle for this parameter
       and an object handle for the obj parameter. For	all  other  functions,
       specifies an object list handle.	 For the st_objlist_append() function,
       specifies the handle of the object to  be  appended  to	the  specified
       object  list  or	 from  which the object list is to be created. For the
       st_objlist_delete() function, specifies the handle of the object to  be
       deleted	from  the specified object list. For the st_objlist_first() or
       st_objlist_last() function, specifies an address to which the  function
       returns	a  handle  to the first or last object in the specified object
       list.  Specifies a text, data, or bss address.  Specifies an address to
       which  a	 given function returns the handle of the object that contains
       the specified text, data, or bss address (st_addr_to_obj), file	handle
       (st_file_to_obj),  procedure  handle (st_proc_to_obj), or symbol handle
       (st_sym_to_obj).	 Specifies a file handle.  Specifies a procedure  han‐
       dle.   For the st_sym_to_obj() function, specifies a symbol handle. For
       the st_objlist_external_name_sym() function, specifies  an  address  to
       which  the  function  returns  the  handle of the first external symbol
       among the objects in the specified object list that matches the name of
       the specified global symbol.  Specifies the name of an external symbol.
       Specifies a routine to be called	 for  each  object  in	the  specified
       object  list.  Specifies data to be input to or output from the routine
       to be called for each object in the specified object  list.   Specifies
       an  address to receive the return value from the specified routine. The
       called routine must be written to return 0 to terminate	its  execution
       within the object list, and ST_FOREACH_CONTINUE to continue to the next
       object.

DESCRIPTION
       These functions create, close, or perform operations on	object	lists:
       Either  creates	a  list of objects or appends an object to an existing
       object list. It either creates a new object list (when  you  specify  a
       NULL  pointer  in  the obj_list parameter) and sets obj_list to the new
       handle, or appends the object to the specified object list.  Deletes an
       object  from an object list. The obj_list parameter is set to the modi‐
       fied object list.  Calls st_obj_close for each object in the  specified
       object  list, and deallocates the memory used for maintaining the list.
       Do not directly call st_obj_close() for any object that is part	of  an
       object  list.   Return  object  handles for the first and last objects,
       respectively, in the specified object list.  Return the handle  of  the
       object  in  the	specified  object  list	 that  contains	 the specified
       address, file, procedure, or symbol.  Note  that	 the  st_addr_to_obj()
       function cannot match a heap address to an object in a running program.
       Searches the external symbols in each object in	the  specified	object
       list  for  a  name  that	 matches  the specified global symbol name and
       returns the handle of the first matching symbol. Note that there may be
       multiple	 external  symbols with the same name in call-shared programs.
       This function returns the symbol from the first object on the list that
       contains	  a   matching	 name.	 For  C++  objects,  st_objlist_exter‐
       nal_name_sym() returns a demangled name if name demangling  is  enabled
       for  the	 object	 in  which the name is found.  By default, objects are
       opened with C++ name-demangling enabled.	 Provides a means of calling a
       routine	once  for  each	 object in the specified object list. You must
       write the called routine so that it returns 0 to terminate  its	execu‐
       tion within the object list, and ST_FOREACH_CONTINUE to continue to the
       next object.

RETURN VALUES
       All functions indicate success by returning a value of 0 (zero). A pos‐
       itive  return  value  is	 an errno value from a system call. A negative
       return value is a library error	or  informational  code.  The  library
       codes are documented in st.h.

       Return  parameters  are	set  to	 0 or -1 when an error occurs. Address
       parameters are set to 0 while file and procedure handles are set to -1.
       An  exception  to  this	is  if	a NULL pointer for the object or other
       return parameter is input. In these cases, the return  parameters  will
       be  unchanged.	A  nonzero return status is the recommended method for
       detecting an error return from a libst function.

       The st_foreach_obj() function  returns  ST_E_NULL_ARGUMENT  if  a  null
       object  list  or	 routine pointer are supplied. It returns a value of 0
       (zero) when the called routine returns 0 to it. Otherwise,  it  returns
       ST_OBJ_END  to  indicate	 that it has reached the end of the objects on
       the list without a successful return from the called routine.

EXAMPLES
       The following code segment shows how to create a list of	 objects.  The
       code  assumes  that object_names[] has been previously initialized with
       the full pathnames of each object, and  that  name_count	 contains  the
       number  of  entries in object_names[]. Note that the object list handle
       is initialized to NULL before the first call to st_objlist_append().

       st_objlist_t *list = NULL; st_obj_t obj;
	   ...	for(i=0; i< name_count; i++) {
	  if((ret = st_obj_open(&obj, object_names[i], ST_RDONLY))) {
	     printf("%s: Open ret = %d\n", object_names[i], ret);
	     exit(1);
	  }
	  if((ret = st_objlist_append(&list, obj))) {
	     printf(%s: Append ret = %d\n", object_names[i], ret);
	     exit(1);
	  }
	   ...

       /*   st_objlist_close   calls   st_obj_close   for   each   object   */
       st_objlist_close(list);

       The following code segment demonstrates the usage of st_foreach_obj(3).
       The called routine checks if an address falls in the text segment of an
       object.

       st_status_t  check_addr(st_obj_t *obj, st_any_t addr, st_any_t *retval)
       {
	  st_status_t ret;
	  st_addr_t text_start;
	  st_addr_t text_size;
	  st_addr_t text_end;

	  if((ret = st_obj_text_start(obj, &text_start)))
	     return ret;
	  if((ret = st_obj_text_size(obj, &text_size)))
	     return ret;
	  text_end = text_start + text_size;

	  if(retval)
	     *retval = 0L;
	  else
	     /* null argument error */

	  /* If address falls in the text segment of */
	  /* this object, stop searching */
	  if((addr >= text_start) && (addr < text_end)) {
	     *retval = (st_any_t)obj;
	     return 0;
	  }

	  /* Check next object */
	  return ST_FOREACH_CONTINUE; }

       main() {
	  st_objlist_t *olist;
	  st_addr_t addr;
	  st_status_t ret;
	  st_obj_t *obj;

	...
	  /* object list previously created and "addr" set to an address */

	  ret = st_foreach_obj(olist, check_addr, addr, (st_any_t *)&obj);
	  if(ret == ST_OBJ_END)
	    /* No object was found containing the address */
	  else
	    /* obj is set to object handle containing the address */
	...

FILES
       Header file that contains all definitions and function  prototypes  for
       libst.a	functions Header file that controls name-demangling operations
       for C++ objects

SEE ALSO
       Commands: atom(1)

       Functions:   libst_intro(3),    st_addr_to_file(3),    st_file_lang(3),
       st_obj_file_start(3), st_obj_open(3), st_proc_addr(3), st_sym_value(3)

							  st_objlist_append(3)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net