scf_service_add_pg 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_PG_CREATE(3SCF)					   SCF_PG_CREATE(3SCF)

NAME
       scf_pg_create,  scf_pg_handle,  scf_pg_destroy,	scf_pg_get_parent_ser‐
       vice,	 scf_pg_get_parent_instance,	  scf_pg_get_parent_snaplevel,
       scf_pg_get_name,	  scf_pg_get_type,   scf_pg_get_flags,	scf_pg_update,
       scf_service_get_pg,	scf_service_add_pg,	  scf_instance_get_pg,
       scf_instance_get_pg_composed,			  scf_instance_add_pg,
       scf_snaplevel_get_pg, scf_pg_delete, scf_pg_get_underlying_pg -	create
       and  manipulate	property group handles and property groups in the Ser‐
       vice Configuration Facility

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

       scf_propertygroup_t *scf_pg_create(scf_handle_t *handle);

       scf_handle_t *scf_pg_handle(scf_propertygroup_t *pg);

       void scf_pg_destroy(scf_propertygroup_t *pg);

       int scf_pg_get_parent_service(const scf_propertygroup_t *pg,
	    scf_service_t *svc);

       int scf_pg_get_parent_instance(const scf_propertygroup_t *pg,
	    scf_instance_t *inst);

       int scf_pg_get_parent_snaplevel(const scf_propertygroup_t *pg,
	    scf_snaplevel_t *level);

       ssize_t scf_pg_get_name(const scf_propertygroup_t *pg, char *buf,
	    size_t size);

       ssize_t scf_pg_get_type(const scf_propertygroup_t *pg, char *buf,
	    size_t size);

       int scf_pg_get_flags(const scf_propertygroup_t *pg, uint32_t *out);

       int scf_pg_update(const scf_propertygroup_t *pg);

       int scf_service_get_pg(const scf_service_t *svc, const char *name,
	    scf_propertygroup_t *pg);

       int scf_service_add_pg(const scf_service_t *svc,
	    const char *name, const char *group_type,
	    uint32_t flags, scf_propertygroup_t *pg);

       int scf_instance_get_pg(const scf_instance_t *inst,
	    const char *name, scf_propertygroup_t *pg);

       int scf_instance_get_pg_composed(const scf_instance_t *inst,
	    const scf_snapshot_t *snapshot, const char *name,
	    scf_propertygroup_t *pg);

       int scf_instance_add_pg(const scf_instance_t *inst,
	    const char *name, const char *group_type, uint32_t flags,
	    scf_propertygroup_t *pg);

       int scf_snaplevel_get_pg(const scf_snaplevel_t *level,
	    const char *name, scf_propertygroup_t *pg);

       int scf_pg_delete(scf_propertygroup_t *pg);

       int scf_pg_get_underlying_pg(const scf_propertygroup_t *pg,
	    scf_propertygroup_t *out);

DESCRIPTION
       Property groups are an atomically-updated group	of  typed  properties.
       Property groups of services (see scf_service_create(3SCF)) or instances
       (see scf_instance_create(3SCF))	are  modifiable.  Property  groups  of
       snaplevels (see scf_snaplevel_create(3SCF)) are not modifiable.

       An  scf_propertygroup_t is an opaque handle that can be set to a single
       property group at any given time. When an scf_propertygroup_t  is  set,
       it  references  a frozen-in-time version of the property group to which
       it is set.  Updates to the property group will  not  be	visible	 until
       either scf_pg_update() is called or the property group is set again.

       This  static  view is propagated to the scf_property_ts set to children
       of the property group. They will not see updates, even if the scf_prop‐
       ertygroup_t is updated.

       The  scf_pg_create() function allocates and initializes a new scf_prop‐
       ertygroup_t bound to handle. The scf_pg_destroy() function destroys and
       frees pg.

       The scf_pg_handle() function retrieves the handle to which pg is bound.

       The   scf_pg_get_parent_service(),   scf_pg_get_parent_instance(),  and
       scf_pg_get_parent_snaplevel() functions retrieve the  property  group's
       parent, if it is of the requested type.

       The scf_pg_get_name() and scf_pg_get_type() functions retrieve the name
       and type, respectively, of the property group to which pg is set.

       The scf_pg_get_flags() function retrieves the flags  for	 the  property
       group  to  which	 pg  is	 set. If SCF_PG_FLAG_NONPERSISTENT is set, the
       property group is not included in snapshots and will lose its  contents
       upon  system  shutdown  or  reboot.  Non-persistent property groups are
       mainly used for smf-internal state. See smf(5).

       The scf_pg_update() function ensures that pg is attached	 to  the  most
       recent version of the pg to which it is set.

       The	  scf_service_get_pg(),	      scf_instance_get_pg(),	   and
       scf_snaplevel_get_pg() functions set pg to the property group specified
       by  name	 in  the  service  specified by svc, the instance specified by
       inst, or the snaplevel specified by level, respectively.

       The scf_instance_get_pg_composed() function sets	 pg  to	 the  property
       group  specified by name in the composed view of inst at the time snap‐
       shot was taken. If snapshot is NULL, the current properties  are	 used.
       The composed view of an instance's properties is the union of the prop‐
       erties of the instance and its ancestors. Properties  of	 the  instance
       take  precedence	 over  properties  of  the  service with the same name
       (including the  property	 group	name).	After  a  successful  call  to
       scf_instance_get_pg_composed(), the parent of pg might not be inst, and
       the parents of properties obtained from pg might not be pg. If inst and
       its parent have property groups with the same name but different types,
       the properties in the property group of the parent are excluded.

       The scf_service_add_pg() and scf_instance_add_pg() functions  create  a
       new  property  group  specified	by  name whose type is group_type, and
       attach the pg handle (if non-null) to the new object. The  flags	 argu‐
       ment must be either 0 or SCF_PG_FLAG_NONPERSISTENT.

       The  scf_pg_delete()  function  deletes the property group. Versions of
       the property group in snapshots are not affected.

       The scf_pg_get_underlying_pg() function gets the first existing	under‐
       lying  property	group.	If  the	 property  group specified by pg is an
       instance property group, out is set to the property group of  the  same
       name in the instance's parent.

       Applications  can  use  a  transaction  to modify a property group. See
       scf_transaction_create(3SCF).

RETURN VALUES
       Upon successful completion, scf_pg_create() returns a new scf_property‐
       group_t. Otherwise, it returns NULL.

       Upon  successful	 completion,  scf_pg_handle() returns a pointer to the
       handle to which pg is bound. Otherwise, it returns NULL.

       Upon successful completion, scf_instance_handle()  returns  the	handle
       instance with which it is associated. Otherwise, it returns NULL.

       Upon  successful	 completion,  scf_pg_get_name()	 and scf_pg_get_type()
       return the length of the string written, not including the  terminating
       null byte. Otherwise, they return -1.

       The  scf_pg_update() function returns 1 if the object was updated, 0 if
       the object was already up to date, and -1 on failure.

       Upon	 successful	 completion,	  scf_pg_get_parent_service(),
       scf_pg_get_parent_snaplevel(),	    scf_pg_get_flags(),	      scf_ser‐
       vice_get_pg(),	scf_service_add_pg(),	 scf_pg_get_parent_instance(),
       scf_instance_get_pg(),		       scf_instance_get_pg_composed(),
       scf_instance_add_pg(),  scf_snaplevel_get_pg(),	scf_pg_delete(),   and
       scf_pg_get_underlying_pg() return 0. Otherwise, they return -1.

ERRORS
       The scf_pg_create() function will fail if:

       SCF_ERROR_INVALID_ARGUMENT

	   The handle argument is NULL.

       SCF_ERROR_NO_MEMORY

	   There is not enough memory to allocate an scf_propertygroup_t.

       SCF_ERROR_NO_RESOURCES

	   The	server	does  not  have	 adequate resources for a new property
	   group handle.

       The scf_pg_handle() function will fail if:

       SCF_ERROR_HANDLE_DESTROYED

	   The handle associated with pg has been destroyed.

       The scf_pg_update() function will fail if:

       SCF_ERROR_CONNECTION_BROKEN

	   The connection to the repository was lost.

       SCF_ERROR_DELETED

	   An ancestor of the property group specified by pg has been deleted.

       SCF_ERROR_INTERNAL

	   An internal error occurred. This can happen if  pg  has  been  cor‐
	   rupted.

       SCF_ERROR_INVALID_ARGUMENT

	   The pg argument refers to an invalid scf_propertygroup_t.

       SCF_ERROR_NOT_BOUND

	   The handle is not bound.

       SCF_ERROR_NOT_SET

	   The property group specified by pg is not set.

       The	       scf_service_get_pg(),		scf_instance_get_pg(),
       scf_instance_get_pg_composed(),	     scf_snaplevel_get_pg(),	   and
       scf_pg_get_underlying_pg() functions will fail if:

       SCF_ERROR_BACKEND_ACCESS

	   The	 storage   mechanism   that  the   repository server (svc.con‐
	   figd(1M)) chose for the operation denied access.

       SCF_ERROR_INTERNAL

	   An internal error occurred.

       SCF_ERROR_NO_RESOURCES

	   The server does not have the resources to complete the request.

       The    scf_pg_get_name(),    scf_pg_get_type(),	   scf_pg_get_flags(),
       scf_pg_get_parent_service(),	scf_pg_get_parent_snaplevel(),	   and
       scf_pg_get_parent_instance() functions will fail if:

       SCF_ERROR_DELETED

	   The property group specified by pg has been deleted.

       SCF_ERROR_NOT_SET

	   The property group specified by pg is not set.

       SCF_ERROR_NOT_BOUND

	   The handle is not bound.

       SCF_ERROR_CONNECTION_BROKEN

	   The connection to the repository was lost.

       The  scf_pg_get_parent_service(),  scf_pg_get_parent_snaplevel(),   and
       scf_pg_get_parent_instance() functions will fail if:

       SCF_ERROR_CONSTRAINT_VIOLATED

	   The	requested  parent  type	 does not match the actual type of the
	   parent of the property group specified by pg.

       SCF_ERROR_HANDLE_MISMATCH

	   The property group and either the instance,	the  service,  or  the
	   snaplevel are not derived from the same handle.

       The   scf_instance_get_pg(),  scf_instance_get_pg_composed(),  scf_ser‐
       vice_get_pg(), scf_pg_get_underlying_pg(),  and	scf_snaplevel_get_pg()
       functions will fail if:

       SCF_ERROR_NOT_FOUND

	   The property group specified by name was not found.

       The  scf_service_add_pg(), scf_service_get_pg(), scf_instance_add_pg(),
       scf_instance_get_pg(),	    scf_instance_get_pg_composed(),	   and
       scf_snaplevel_get_pg() functions will fail if:

       SCF_ERROR_DELETED

	   The service or instance has been deleted.

       SCF_ERROR_NOT_SET

	   The instance is not set.

       SCF_ERROR_INVALID_ARGUMENT

	   The value of the name argument is not a valid property group name.

       SCF_ERROR_HANDLE_MISMATCH

	   The	property  group	 and  either the instance, the service, or the
	   level are not derived from the same handle.

       SCF_ERROR_NOT_BOUND

	   The handle is not bound.

       SCF_ERROR_CONNECTION_BROKEN

	   The connection to the repository was lost.

       The scf_service_add_pg() and scf_instance_add_pg() functions will  fail
       if:

       SCF_ERROR_PERMISSION_DENIED

	   The	caller	does not have permission to create the requested prop‐
	   erty group.

       SCF_ERROR_BACKEND_READONLY

	   The repository backend is read-only.

       SCF_ERROR_BACKEND_ACCESS

	   The repository backend refused the modification.

       SCF_ERROR_EXISTS

	   A {service,instance,property group} named name already exists.

       SCF_ERROR_NO_RESOURCES

	   The server does not have the resources to complete the request.

       The scf_pg_delete() function will fail if:

       SCF_ERROR_BACKEND_ACCESS

	   The repository backend refused the modification.

       SCF_ERROR_BACKEND_READONLY

	   The repository backend is read-only.

       SCF_ERROR_CONNECTION_BROKEN

	   The connection to the repository was lost.

       SCF_ERROR_DELETED

	   The property group has been deleted by someone else.

       SCF_ERROR_NO_RESOURCES

	   The server does not have adequate  resources	 for  a	 new  property
	   group handle.

       SCF_ERROR_NOT_SET

	   The property group has not been set.

       SCF_ERROR_PERMISSION_DENIED

	   The caller does not have permission to delete this property group.

       The scf_pg_get_underlying_pg() function will fail if:

       SCF_ERROR_CONNECTION_BROKEN

	   The connection to the repository was lost.

       SCF_ERROR_CONSTRAINT_VIOLATED

	   A required constraint was not met.

       SCF_ERROR_DELETED

	   The property group has been deleted.

       SCF_ERROR_HANDLE_MISMATCH

	   The property group and out are not derived from the same handle.

       SCF_ERROR_INVALID_ARGUMENT

	   An argument is invalid.

       SCF_ERROR_NOT_BOUND

	   The handle is not bound.

       SCF_ERROR_NOT_SET

	   The property group has not been set.

       The scf_error(3SCF) function can be used to retrieve the error value.

EXAMPLES
       Example 1 Perform a layered lookup of name in pg.

	 int layered_lookup(scf_propertygroup_t *pg, const char *name,
	 scf_property_t *out) {
	      scf_handle_t *handle = scf_pg_handle(out);
	      scf_propertygroup_t *new_pg;
	      scf_propertygroup_t *cur, *other;
	      int state = 0;

	      if (handle == NULL) {
		   return (-1);
	      }
	      new_pg = scf_pg_create(handle);
	      if (new_pg == NULL) {
		   return (-1);
	      }
	      for (;;) {
		   cur =   state ? pg : new_pg;
		   other = state ? new_pg : pg;
		   state = !state;

		   if (scf_pg_get_property(cur, name, out) != -1) {
			scf_pg_destroy(new_pg);
			return (SUCCESS);
		   }
		   if (scf_pg_get_underlying_pg(cur, other) == -1)
			break;
	      }
	      scf_pg_destroy(new_pg);
	      return (NOT_FOUND);
	 }

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),	 scf_handle_decode_fmri(3SCF),
       scf_instance_create(3SCF),    scf_pg_to_fmri(3SCF),    scf_service_cre‐
       ate(3SCF),   scf_snaplevel_create(3SCF),	 scf_transaction_create(3SCF),
       attributes(5), smf(5)

				 Jun 29, 2009		   SCF_PG_CREATE(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