scf_simple_app_props_get man page on SmartOS

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

SCF_SIMPLE_PROP_GET(3SCF)			     SCF_SIMPLE_PROP_GET(3SCF)

NAME
       scf_simple_prop_get,   scf_simple_prop_free,  scf_simple_app_props_get,
       scf_simple_app_props_free,     scf_simple_app_props_next,      scf_sim‐
       ple_app_props_search,  scf_simple_prop_numvalues, scf_simple_prop_type,
       scf_simple_prop_name,	     scf_simple_prop_pgname,	      scf_sim‐
       ple_prop_next_boolean,	    scf_simple_prop_next_count,	      scf_sim‐
       ple_prop_next_integer,	    scf_simple_prop_next_time,	      scf_sim‐
       ple_prop_next_astring,	   scf_simple_prop_next_ustring,      scf_sim‐
       ple_prop_next_opaque, scf_simple_prop_next_reset - simplified  property
       read interface to Service Configuration Facility

SYNOPSIS
       cc [ flag... ] file... -lscf [ library... ]
       #include <libscf.h>

       scf_simple_prop_t *scf_simple_prop_get(scf_handle_t *handle,
	    const char *instance, const char *pgname, const char *propname);

       void scf_simple_prop_free(scf_simple_prop_t *prop);

       scf_simple_app_props_t *scf_simple_app_props_get(scf_handle_t *handle,
	    const char *instance);

       void scf_simple_app_props_free(scf_simple_app_props_t *propblock);

       const scf_simple_prop_t *scf_simple_app_props_next
	    (const scf_simple_app_props_t *propblock,scf_simple_prop_t *last);

       const scf_simple_prop_t *scf_simple_app_props_search
	    (const scf_simple_app_props_t *propblock, const char *pgname,
	    const char *propname);

       ssize_t scf_simple_prop_numvalues(const scf_simple_prop_t *prop);

       scf_type_t scf_simple_prop_type(const scf_simple_prop_t *prop);

       const char *scf_simple_prop_name(const scf_simple_prop_t *prop);

       const char *scf_simple_prop_pgname(const scf_simple_prop_t *prop);

       uint8_t *scf_simple_prop_next_boolean(const scf_simple_prop_t *prop);

       uint64_t *scf_simple_prop_next_count(const scf_simple_prop_t *prop);

       int64_t *scf_simple_prop_next_integer(const scf_simple_prop_t *prop);

       int64_t *scf_simple_prop_next_time(const scf_simple_prop_t *prop,
	    int32_t *nsec);

       char *scf_simple_prop_next_astring(const scf_simple_prop_t *prop);

       char *scf_simple_prop_next_ustring(const scf_simple_prop_t *prop);

       void *scf_simple_prop_next_opaque(const scf_simple_prop_t *prop,
	    size_t *length);

       void *scf_simple_prop_next_reset(const scf_simple_prop_t *prop);

DESCRIPTION
       The  simplified	read  interface	 to the Service Configuration Facility
       deals with properties and blocks of properties.

       The  scf_simple_prop_get()  function  pulls  a  single  property.   The
       scf_simple_prop_*()   functions	 operate  on  the  resulting  scf_sim‐
       ple_prop_t.

       The application might need to get many properties  or  iterate  through
       all  properties. The scf_simple_app_props_get() function gets all prop‐
       erties from the service instance that are in property  groups  of  type
       'application'.	Individual  properties are pulled from the block using
       the scf_simple_app_props_next()	function  for  iteration  or  scf_sim‐
       ple_app_props_search()  to search. The pointer to the scf_simple_prop_t
       returned from iteration or  searching  can  be  acted  upon  using  the
       scf_simple_prop_*()  functions. Each scf_*_get() function has an accom‐
       panying scf_*_free function. The application does not free the  pointer
       to  the scf_simple_prop_t returned from the scf_simple_app_props_next()
       and scf_simple_app_props_search() calls. A free call is only used  with
       a corresponding get call.

       The  scf_simple_prop_*()	 functions  return references to the read-only
       in-memory copy of the property information. Any changes to this	infor‐
       mation results in unstable behavior and inaccurate results. The simpli‐
       fied read interface provides read access only, with  no	provisions  to
       modify data in the service configuration facility repository.

       The scf_simple_prop_get() function takes as arguments a bound handle, a
       service instance FMRI, and the property group and property  name	 of  a
       property.   If handle is NULL, the library uses a temporary handle cre‐
       ated for the purpose. If instance is  NULL  the	library	 automatically
       finds  the  FMRI of the calling process. If pgname is NULL, the library
       uses the default application property group. The caller is  responsible
       for freeing the returned property with scf_simple_prop_free().

       The  scf_simple_prop_free()  function frees the scf_simple_prop_t allo‐
       cated by scf_simple_prop_get().

       The scf_simple_app_props_get() function takes a bound handle and a ser‐
       vice  instance  FMRI  and  pulls all the application properties into an
       scf_simple_app_props_t. If handle is NULL, the library uses a temporary
       handle  created for the purpose. If instance is NULL, the library looks
       up the instance FMRI of the process calling the function. The caller is
       responsible   for  freeing  the	scf_simple_app_props_t	with  scf_sim‐
       ple_app_props_free().

       The   scf_simple_app_props_free()   function   frees    the    scf_sim‐
       ple_app_props_t allocated by scf_simple_app_props_get().

       The scf_simple_app_props_next() function iterates over each property in
       an scf_simple_app_props_t. It takes an  scf_simple_app_props_t  pointer
       and  the	 last property returned from the previous call and returns the
       next property in the scf_simple_app_props_t. Because the property is  a
       reference  into	the  scf_simple_app_props_t, its lifetime extends only
       until that structure is freed.

       Thescf_simple_app_props_search() function queries for an exact match on
       a  property  in a property group. It takes an apps prop object, a prop‐
       erty group name, and a property name, and returns a  property  pointer.
       Because	the  property  is a reference into the scf_simple_app_props_t,
       its lifetime extends only until that structure is freed. If  the	 prop‐
       erty group name, pgname, is NULL, "application" is used.

       The  scf_simple_prop_numvalues() function takes a pointer to a property
       and returns the number of values in that property.

       The scf_simple_prop_type() function takes a pointer to a	 property  and
       returns the type of the property in an scf_type_t.

       The  scf_simple_prop_name()  function takes a pointer to a property and
       returns a pointer to the property name string.

       The scf_simple_prop_pgname() function takes a pointer to a property and
       returns	a  pointer  to	the  property  group name string. The scf_sim‐
       ple_prop_next_boolean(),	    scf_simple_prop_next_count(),     scf_sim‐
       ple_prop_next_integer(),	 scf_simple_prop_next_astring(),  and scf_sim‐
       ple_prop_next_ustring() functions take a	 pointer  to  a	 property  and
       return  the first value in the property.	 Subsequent calls iterate over
       all the values in the property. The property's internal	iteration  can
       be reset with scf_simple_prop_next_reset().

       The  scf_simple_prop_next_time() function takes a pointer to a property
       and the address of an allocated int32_t to hold the nanoseconds	field,
       and  returns  the first value in the property. Subsequent calls iterate
       over the property values.

       The scf_simple_prop_next_opaque() function takes a pointer to  a	 prop‐
       erty  and  the  address of an allocated integer to hold the size of the
       opaque buffer.  It returns the first value in the property.  Subsequent
       calls   iterate	 over	the   property	values,	 as  do	 the  scf_sim‐
       ple_prop_next_*() functions. The scf_simple_prop_next_opaque() function
       writes the size of the opaque buffer into the allocated integer.

       The  scf_simple_prop_next_reset()  function resets iteration on a prop‐
       erty, so that a call to one of the  scf_simple_prop_next_*()  functions
       returns the first value in the property.

RETURN VALUES
       Upon  successful completion, scf_simple_prop_get() returns a pointer to
       an allocated scf_simple_prop_t. Otherwise, it returns NULL.

       Upon  successful	 completion,  scf_simple_app_props_get()   returns   a
       pointer	to  an allocated scf_simple_app_props_t. Otherwise, it returns
       NULL.

       Upon  successful	 completion,  scf_simple_app_props_next()  returns   a
       pointer to an scf_simple_prop_t. Otherwise, it returns NULL.

       Upon  successful	 completion,  scf_simple_app_props_search()  returns a
       pointer to an scf_simple_prop_t. Otherwise, it returns NULL.

       Upon successful	completion,  scf_simple_prop_numvalues()  returns  the
       number of values in a property. Otherwise, it returns -1.

       Upon   successful   completion,	 scf_simple_prop_type()	  returns   an
       scf_type_t. Otherwise, it returns -1.

       Upon  successful	 completion,   scf_simple_prop_name()	and   scf_sim‐
       ple_prop_pgname()  return  character  pointers.	Otherwise, they return
       NULL.

       Upon successful	completion,  scf_simple_prop_next_boolean(),  scf_sim‐
       ple_prop_next_count(),	  scf_simple_prop_next_integer(),     scf_sim‐
       ple_prop_next_time(),	 scf_simple_prop_next_astring(),      scf_sim‐
       ple_prop_next_ustring(),	 and  scf_simple_prop_next_opaque()  return  a
       pointer to the next value in the property. After all values  have  been
       returned,  NULL is returned and SCF_ERROR_NONE is set. On failure, NULL
       is returned and the appropriate error value is set.

ERRORS
       The scf_simple_prop_get() and scf_simple_app_props_get() functions will
       fail if:

       SCF_ERROR_CONNECTION_BROKEN

	   The connection to the datastore is broken.

       SCF_ERROR_INVALID_ARGUMENT

	   The instance FMRI is invalid or property name is NULL.

       SCF_ERROR_NO_MEMORY

	   The memory allocation failed.

       SCF_ERROR_NOT_BOUND

	   The connection handle is not bound.

       SCF_ERROR_NOT_FOUND

	   The specified instance or property does not exist.

       SCF_ERROR_PERMISSION_DENIED

	   The caller is not authorized to read the property's value(s).

       The scf_simple_app_props_next() function will fail if:

       SCF_ERROR_NOT_SET
			    The value of the propblock argument is NULL.

       The scf_simple_app_props_search() function will fail if:

       SCF_ERROR_NOT_FOUND
			      The property was not found.

       SCF_ERROR_NOT_SET
			      The  value of the propblock or propname argument
			      is NULL.

       The   scf_simple_prop_numvalues(),   scf_simple_prop_type(),   scf_sim‐
       ple_prop_name(), and scf_simple_prop_pgname() functions will fail if:

       SCF_ERROR_NOT_SET
			    The property is NULL.

       The    scf_simple_prop_next_boolean(),	 scf_simple_prop_next_count(),
       scf_simple_prop_next_integer(),	scf_simple_prop_next_time(),  scf_sim‐
       ple_prop_next_astring(),	 scf_simple_prop_next_ustring(),  and scf_sim‐
       ple_prop_next_opaque() functions will fail if:

       SCF_ERROR_NOT_SET
				  The property is NULL.

       SCF_ERROR_TYPE_MISMATCH
				  The requested type does not match the	 prop‐
				  erty type.

EXAMPLES
       Example 1 Simple Property Get

	 /*
	  * In this example, we pull the property named "size" from the
	  * default property group.  We make sure that the property
	  * isn't empty, and then copy it into the sizeval variable.
	  */

	 scf_simple_prop_t	 *prop;
	 ssize_t		 numvals;
	 int64_t		 *sizeval;

	 prop = scf_simple_prop_get(
		 "svc://localhost/category/service/instance",
		 NULL, "size");

	 numvals = scf_simple_prop_numvalues(prop);

	 if(numvals > 0){
		 sizeval = scf_simple_prop_next_integer(prop);
	 }

	 scf_simple_prop_free(prop);

       Example 2 Property Iteration

	 scf_simple_prop_t		*prop;
	 scf_simple_app_props_t		*appprops;

	 appprops = scf_simple_app_props_get(
		 "svc://localhost/category/service/instance");

	 prop = scf_simple_app_props_next(appprops, NULL);

	 while(prop != NULL)
	 {
		 /*
		  * This iteration will go through every property in the
		  * instance's application block.  The user can use
		  * the set of property functions to pull the values out
		  * of prop, as seen in other examples.
		  */

		 (...code acting on each property...)

	 prop = scf_simple_app_props_next(appprops, prop);

	 }

	 scf_simple_app_props_free(appprops);

       Example 3 Property Searching

	 /*
	  * In this example, we pull the property block from the instance,
	  * and then query it.	Generally speaking, the simple get would
	  * be used for an example like this, but for the purposes of
	  * illustration, the non-simple approach is used.  The property
	  * is a list of integers that are pulled into an array.
	  * Note how val is passed back into each call, as described above.
	  */

	 scf_simple_app_props_t		*appprops;
	 scf_simple_prop_t		*prop;
	 int			 i;
	 int64_t		 *intlist;
	 ssize_t		 numvals;

	 appprops = scf_simple_app_props_get(
		       "svc://localhost/category/service/instance");

	 prop = scf_simple_app_props_search(appprops, "appname", "numlist");

	 if(prop != NULL){

		 numvals = scf_simple_prop_numvalues(prop);

		 if(numvals > 0){

		 intlist = malloc(numvals * sizeof(int64_t));

		 val = scf_simple_prop_next_integer(prop);

			 for(i=0, i < numvals, i++){
				 intlist[i] = *val;
				 val = scf_simple_prop_next_integer(prop);
			 }
		 }
	 }

	 scf_simple_app_props_free(appprops);

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Committed	      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ Safe	      │
       └────────────────────┴─────────────────┘

SEE ALSO
       libscf(3LIB), scf_error(3SCF), attributes(5)

				  Nov 7, 2007	     SCF_SIMPLE_PROP_GET(3SCF)
[top]

List of man pages available for SmartOS

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