Service Configuration Facility Library Functions
                                     scfhandledecodefmri(3SCF)



NAME
     scfhandledecodefmri,                   scfscopetofmri,
     scfservicetofmri,  scfinstancetofmri,  scfpgtofmri,
     scfpropertytofmri - convert between objects and FMRIs  in
     the Service Configuration Facility

SYNOPSIS
     cc [ flag... ] file... -lscf [ library... ]
     #include 

     scfhandledecodefmri(scfhandlet *handle, const char *fmri,
          scfscopet *scope, scfservicet *service,
          scfinstancet *instance, scfpropertygroupt *pg,
           scfpropertyt *property, int flag);


     ssizet scfscopetofmri(const scfscopet *object,
          char *buffer, sizet sz);


     ssizet scfservicetofmri(const scfscopet *object,
          char *buffer, sizet sz);


     ssizet scfinstancetofmri(const scfinstancet *inst,
          char *buffer, sizet sz);


     ssizet scfpgtofmri(const scfpropertygroupt *pg, char *out,
          sizet sz);


     ssizet scfpropertytofmri(const scfscopet *object,
          char *buffer, sizet sz);


DESCRIPTION
     The scfhandledecodefmri() function decodes an FMRI string
     into  a  set of repository entries. Any number of the entity
     handles can be NUL. The validation and decoding of the FMRI
     are  determined by the flags argument and by those arguments
     that are NUL.


     If flags == 0, any FMRI is accepted as long as it  is  well-
     formed and exists in the repository.


     If SCFDECODEFMRIEXACT is set in flags, the last  part  of
     the  FMRI  must  match  the last non-null entity handle. For
     example, if property is NUL and pg is  non-null,  the  FMRI



SunOS 5.11          Last change: 23 Apr 2008                    1






Service Configuration Facility Library Functions
                                     scfhandledecodefmri(3SCF)



     must be a property group FMRI.


     If SCFDECODEFMRITRUNCATE is set in  flags,  there  is  no
     check for the existence of any objects specified in the FMRI
     that follow the last non-null entity handle. For example, if
     property  is  NUL,  pg  is non-null, and a property FMRI is
     passed in, scfhandledecodefmri() succeeds as long as  the
     property  group exists, even if the referenced property does
     not exist.


     If           SCFDECODEFMRIREQUIREINSTANCE            (or
     SCFMRIREQUIRENOINSTANCE) is set in flags, then the FMRI
     must (or must not) specify an instance.


     If an error occurs, all of  the  entity  handles  that  were
     passed to the function are reset.


     The       scfscopetofmri(),        scfservicetofmri(),
     scfinstancetofmri(),         scfpgtofmri(),        and
     scfpropertytofmri() functions convert an entity handle to
     an FMRI.

RETURN VALUES
     Upon successful completion, scfhandledecodefmri() returns
     0. Otherwise, it returns -1.


     Upon     successful     completion,     scfscopetofmri(),
     scfservicetofmri(),               scfinstancetofmri(),
     scfpgtofmri(),  and  scfpropertytofmri()  return   the
     length of the FMRI. The buffer will be null-terminated if sz
     > 0, similar to  strlcpy(3C). Otherwise, they return -1  and
     the contents of buffer are undefined.

ERORS
     The scfhandledecodefmri() function will fail if:

     SCFERORBACKENDACES

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


     SCFERORCONECTIONBROKEN

         The connection to the repository was lost.




SunOS 5.11          Last change: 23 Apr 2008                    2






Service Configuration Facility Library Functions
                                     scfhandledecodefmri(3SCF)



     SCFERORCONSTRAINTVIOLATED

         The FMRI does not meet the restrictions requested in the
         flag argument.


     SCFERORDELETED

         The object argument refers to an object  that  has  been
         deleted.


     SCFERORHANDLEMISMATCH

         One or more of the entity handles was not  derived  from
         handle.


     SCFERORINTERNAL

         An internal error occurred.


     SCFERORINVALIDARGUMENT

         The fmri argument is not a valid FMRI.


     SCFERORNORESOURCES

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


     SCFERORNOTBOUND

         The handle is not currently bound.


     SCFERORNOTFOUND

         The FMRI is well-formed but there is no  object  in  the
         repository matching it.


     SCFERORNOTSET

         Cannot use unset value.






SunOS 5.11          Last change: 23 Apr 2008                    3






Service Configuration Facility Library Functions
                                     scfhandledecodefmri(3SCF)



     The       scfscopetofmri(),        scfservicetofmri(),
     scfinstancetofmri(),         scfpgtofmri(),        and
     scfpropertytofmri() functions will fail if:

     SCFERORNOTSET

         The object argument is not currently set.


     SCFERORDELETED

         The object argument refers to an object  that  has  been
         deleted.


     SCFERORNOTBOUND

         The handle is not currently bound.


     SCFERORCONECTIONBROKEN

         The connection to the repository was lost.



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

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Committed                   
    
     MT-Level                     Safe                        
    


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








SunOS 5.11          Last change: 23 Apr 2008                    4






Service Configuration Facility Library Functions
                                     scfhandledecodefmri(3SCF)






















































SunOS 5.11          Last change: 23 Apr 2008                    5