From sacadmin Thu Jul 18 17:47:01 2002 Date: Thu, 18 Jul 2002 17:43:56 -0700 (PDT) From: Shudong Zhou Subject: PSARC 2002/421 Veritas Contract for Devfsadm Interfaces To: psarc@sac.eng.sun.com Cc: Johnny.Hui@Sun.COM, ravi.srinivasan@Sun.COM, io-frameworks@eng.sun.com MIME-Version: 1.0 Content-Type: TEXT/plain; charset=us-ascii Content-MD5: iUmDAkt1xL2kawgPuChxYw== Content-Length: 3103 I'm submitting the following fasttrack for Johnny Hui. The timer is set to expire on 07/25/02. A copy of the contract is placed in the case directory. Shudong This case proposes to contract the following interfaces to Veritas: Libdevinfo devlinks INTERFACE (PSARC 2000/310): =============================================== a) di_devlink_handle_t di_devlink_init(const char *drv, uint_t flags); b) int di_devlink_fini(di_devlink_handle_t *pp); c) DI_MAKE_LINK +----------------------------------------------------------------------------+ | Devfsadm Loadable Module interfaces (PSARC 1998/416) | | ==================================================== | | | | devfsadm_create_t | Sun Private | callback reg. structure | | TYPE_{EXACT, RE, PARTIAL} | Sun Private | minor nodetype match | | DRV_{EXACT, RE} | Sun Private | driver name match criteria | | ILEVEL_0 | Sun Private | callback interpose level | | int (*create_callback)() | Sun Private | minor create callback fcn | | DEVFSADM_CREATE_INIT_V0 | Sun Private | registration initializer | | devfsadm_remove_t | Sun Private | callback reg. structure | | int (*remove_callback)() | Sun Private | link removal callback fcn. | | RM_{HOT, PRE, POST, ALWAYS} | Sun Private | remove callback reg. flags | | DEVFSADM_REMOVE_INIT_V0 | Sun Private | registration initializer | | DEVFSADM_{SUCCESS, FAILURE} | Sun Private | return values | | DEVFSADM_{TRUE, FALSE} | Sun Private | return values | | DEVFSADM_{CONTINUE, TERMINATE} | Sun Private | callback return value | | devfsadm_mklink() | Sun Private | Create logical link | | devfsadm_rm_all() | Sun Private | remove logical link / nodes | | devfsadm_rm_link() | Sun Private | remove link | | devfsadm_print() | Sun Private | printing function | | devfsadm_errprint() | Sun Private | error reporting | | VERBOSE_MID | Sun Private | used in devfsadm_print | | INFO_MID | Sun Private | used in devfsadm_print | +----------------------------------------------------------------------------+ These interfaces allow VERITAS to fully adopt to libdevinfo/devfsadm API as requested by Solaris I/O team. The devlinks INTERFACES address problems due to the asynchronous nature of /dev link creation in response to device node creation by a driver. The devfsadm INTERFACES allow VERITAS to build devfsadm loadable module for VERITAS Volume Manager. Currently, VERITAS is manually doing mknod in /dev for their /dev/vx devices. This is out-of-sync with devfs framework and could be problematic in future releases as devfs interface changes. By contracting devfs INTERFACES to VERITAS, VERITAS can adhear to devfs framework. From sacadmin Thu Mar 20 11:37:38 2008 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id m2KIbcCv009322 for ; Thu, 20 Mar 2008 11:37:38 -0700 (PDT) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail3mpk.sfbay.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.2) with ESMTP id m2KIbbbF001211 for <@sunmail2sca.sfbay.sun.com:psarc@sun.com>; Thu, 20 Mar 2008 11:37:38 -0700 (PDT) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0JY100F0PL2NH700@brm-avmta-1.central.sun.com> for psarc@sun.com (ORCPT psarc@sun.com); Thu, 20 Mar 2008 12:37:35 -0600 (MDT) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0JY1008ETL2MXZ80@brm-avmta-1.central.sun.com> for psarc@sun.com (ORCPT psarc@sun.com); Thu, 20 Mar 2008 12:37:34 -0600 (MDT) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id m2KIbYa3000884 for ; Thu, 20 Mar 2008 18:37:34 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java System Messaging Server 6.2-8.04 (built Feb 28 2007)) id <0JY100J01KMZ7H00@mail-amer.sun.com> (original mail from Mark.Carlson@Sun.COM) for psarc@sun.com (ORCPT psarc@sun.com); Thu, 20 Mar 2008 12:37:34 -0600 (MDT) Received: from dhcp-ubrm03-174-80.Central.Sun.COM ([129.147.174.80]) by mail-amer.sun.com (Sun Java System Messaging Server 6.2-8.04 (built Feb 28 2007)) with ESMTPSA id <0JY100G41L201970@mail-amer.sun.com> for psarc@sun.com (ORCPT psarc@sun.com); Thu, 20 Mar 2008 12:37:12 -0600 (MDT) Date: Thu, 20 Mar 2008 12:37:11 -0600 From: "Mark A. Carlson" Subject: Updated contract for PSARC 2002/421 Veritas Contract for Devfsadm Interfaces Sender: Mark.Carlson@sun.com To: PSARC Cc: Mark Schein Message-id: <47E2AED7.3070802@sun.com> MIME-version: 1.0 Content-type: multipart/alternative; boundary="Boundary_(ID_CbFLhOcH09OSGLc/F4tqPA)" X-PMX-Version: 5.4.1.325704 User-Agent: Thunderbird 2.0.0.12 (Macintosh/20080213) Status: RO Content-Length: 61651 This is a multi-part message in MIME format. --Boundary_(ID_CbFLhOcH09OSGLc/F4tqPA) Content-type: text/plain; format=flowed; charset=ISO-8859-1 Content-transfer-encoding: 7BIT This email amends http://sac.sfbay/PSARC/2002/421/contract-01 to cover Veritas's use of "devfsadm_root_path". The updated contract is in the case directory. CHANGES: Update the "CONSUMER" to the current team. Product or Bundle: VERITAS Volume Manager / Veritas Storage Foundation (which included VxVM) Consolidation: N/A Department or Group: Business Partner Software Engineering (BPSE) Bugtraq Category/SubCategory: nws_veritas_storage_foundation Responsible Manager: Denise.Vitt@Sun.com Email alias for team: vmfs-pde@sun.com Add to section 4 "The INTERFACES": On the "Devfsadm Loadable Module INTERFACES" table need to add row: | devfsadm_root_path | Sun Private | return current root update path | In section 2 "The SUPPLIER (definer and/or implementor) is identified by the following" It already reference "Product or Bundle" Solaris 9+ I'd like to ensure it means Solaris 10 too. Could this be changed to says Solaris 9, 10, and11 or OpenSolaris Emails from Veritas development engineering - prasanna_narayana@symantec.com Engineering Manager: > For a zones solution, VxVM started using devfsadm plugin(a private > interface) to create device nodes > > - We are building our source with a private copy of devfsadm.h(from > opensolaris) as the header file is not > publicly available to create our own devfs dynamic .so library. > - The plugin uses the following devfs calls : > > devfsadm_root_path > devfsadm_mklink > devfsadm_rm_all > - It links with libdevinfo > > Could you make sure that you will put some sort of agreement to notify > if the above changes ? NEW CONTRACT: -------------------------- CONTRACT FOR CONTRACT PRIVATE INTERFACES 0. Number: PSARC/2002/421 1. This contract is between a SUPPLIER of INTERFACES and a CONSUMER of those INTERFACES, both of whom are entities within Sun Microsystems, Incorporated. 2. The SUPPLIER (definer and/or implementor) is identified by the following: Product or Bundle: Solaris 9, 10, and greater Consolidation: ON Department or Group: Solaris I/O Group Bugtraq Category/SubCategory: Kernel/devfs Responsible Manager: Cindy Sabenorio 3. The CONSUMER is identified by the following: Product or Bundle: VERITAS Volume Manager (aka Veritas Storage Foundation) Consolidation: N/A Department or Group: Business Partner Software Engineering (BPSE) Bugtraq Category/SubCategory: nws_veritas_storage_foundation/vxvm, sevm/vxvm Responsible Manager: Denise Vitt Department Alias: vmfs-pde@sun.com 4. The INTERFACES are: Libdevinfo devlinks INTERFACE: ============================== a) di_devlink_handle_t di_devlink_init(const char *drv, uint_t flags); b) int di_devlink_fini(di_devlink_handle_t *pp); c) DI_MAKE_LINK +----------------------------------------------------------------------------+ | Devfsadm Loadable Module INTERFACES: | | ==================================== | | | | devfsadm_create_t | Sun Private | callback reg. structure | | TYPE_{EXACT, RE, PARTIAL} | Sun Private | minor nodetype match | | DRV_{EXACT, RE} | Sun Private | driver name match criteria | | ILEVEL_0 | Sun Private | callback interpose level | | int (*create_callback)() | Sun Private | minor create callback fcn | | DEVFSADM_CREATE_INIT_V0 | Sun Private | registration initializer | | devfsadm_remove_t | Sun Private | callback reg. structure | | int (*remove_callback)() | Sun Private | link removal callback fcn. | | RM_{HOT, PRE, POST, ALWAYS} | Sun Private | remove callback reg. flags | | DEVFSADM_REMOVE_INIT_V0 | Sun Private | registration initializer | | DEVFSADM_{SUCCESS, FAILURE} | Sun Private | return values | | DEVFSADM_{TRUE, FALSE} | Sun Private | return values | | DEVFSADM_{CONTINUE, TERMINATE} | Sun Private | callback return value | | devfsadm_mklink() | Sun Private | Create logical link | | devfsadm_rm_all() | Sun Private | remove logical link / nodes | | devfsadm_rm_link() | Sun Private | remove link | | devfsadm_print() | Sun Private | printing function | | devfsadm_errprint() | Sun Private | error reporting | | VERBOSE_MID | Sun Private | used in devfsadm_print | | INFO_MID | Sun Private | used in devfsadm_print | | devfsadm_root_path() | Sun Private | current root update path | +----------------------------------------------------------------------------+ 5. The ARC controlling these INTERFACES is: PSARC 6. The CASE describing these INTERFACES are: PSARC/2000/310, PSARC/2002/239, and PSARC/1997/202, 1998/275, 1998/416 and 1999/473 7b. Although the stability level doesn't normally allow it, CONSUMER will expose INTERFACES to a PARTNER, which is external to Sun, namely: Name of Company: VERITAS Software Corporation Department or Group: VERITAS Volume Manager Development Team Responsible Manager: Umesh Toprani 7d. Changes to INTERFACES requires ARC approval. If SUPPLIER decides to change (including replace or remove) any portion of the INTERFACES, SUPPLIER will notify CONSUMER of the proposed new version, no later than the application for ARC approval of the new version. If SUPPLIER and CONSUMER are contained in the same bundle, they have the option of arranging for simultaneous conversion to the new interfaces. If this is not possible, or if they are not in the same bundle, then SUPPLIER will either make best effort to work with CONSUMER so that CONSUMER can detect which version of INTERFACES is being supplied, or else SUPPLIER will make best effort to supply both old and new versions of INTERFACES. If SUPPLIER cannot make both versions of INTERFACES available, and SUPPLIER and CONSUMER cannot devise a method whereby CONSUMER can detect which version of INTERFACES is being supplied, and the old version of CONSUMER will not run with the new version of SUPPLIER, then either the EOL process must be followed by SUPPLIER, or else a major release of SUPPLIER will be required. [Note not in contract. To protect against mismatches in contract private interfaces between non-co-bundled components, such interfaces must include adequate versioning provisions to deal with reasonably anticipatable changes. The release number returned by uname -r will in some cases be sufficient to determine which version of a Solaris-bundled interface exists.] 8. If CONSUMER requires changes in INTERFACES, SUPPLIER will make best effort to accommodate such changes, which shall then be treated in accordance with paragraph 7 above. 9. Notwithstanding paragraphs 7 and 8, a change to any portion of the INTERFACES shall be regarded as a completely new set of INTERFACES, and requires execution of a new contract. 10. SUPPLIER and CONSUMER agree that evolution of INTERFACES shall be handled as follows: Proposed changes will be reviewed by BPSE and VERITAS Volume Manager Development Team. 11. SUPPLIER and CONSUMER agree that INTERFACES will be supported as follows: The INTERFACES will be maintained on Sun SPARC platforms that VERITAS Volume Manager 3.5 and higher runs on. VERITAS will deploy the INTERFACES on Solaris 9 and above. SUPPLIER and CONSUMER will report problems through Bugtraq. 12. SUPPLIER and CONSUMER agree that INTERFACES will be documented as follows: LIBDEVINFO DEVLINKS INTERFACES: ------------------------------- SYNOPSIS #include di_devlink_handle_t di_devlink_init(const char *name, uint_t flags); int di_devlink_fini(di_devlink_handle_t *hdlp); DESCRIPTION di_devlink_init() takes a snapshot of devlinks and returns a handle to this snapshot. di_devlink_fini() destroys the snapshot and frees the associated memory. a) di_devlink_handle_t di_devlink_init(const char *name, uint_t flags); ARGUMENTS flags Currently the following flags are supported: DI_MAKE_LINK Create devlinks to reflect current state of the kernel device tree before taking the snapshot. Use of this flag requires superuser permissions. name If flags is DI_MAKE_LINK, name specifies the set of minors for which devlinks are to be created. A NULL value selects all minors on the system. If flags is 0, the first argument should be NULL. name can be one of the following: - driver name - physical path to the root of a subtree (without /devices prefix) RETURN VALUES di_devlink_init() On success, a handle to the snapshot is returned. Otherwise, NULL is returned and errno is set to indicate the error. ERRORS di_devlink_init() EINVAL invalid argument(s) ENOMEM insufficient memory With the DI_MAKE_LINK flag, the following may also be returned: EPERM not superuser b) int di_devlink_fini(di_devlink_handle_t *pp); ARGUMENTS pp Pointer to a handle to the snapshot. RETURN VALUES di_devlink_fini() Upon success, 0 is returned. Otherwise, -1 is returned and errno is set to indicate the error. ERRORS di_devlink_fini() EINVAL invalid snapshot handle. DEVFSADM LOADABLE MODULE INTERFACES: ------------------------------------ a) devfsadm_create_t - Link Creation Registration NAME devfsadm_create_t - devfsadm(1M) logical link processing specification. SYNOPSIS #include Loadable modules may register one or more link creation callback functions with devfsadm(1M) by statically initializing a table of devfsadm_create_t structures, specifying the matching criteria that are used by devfsadm(1M) to select which callbacks to invoke. DESCRIPTION typedef struct devfsadm_create { char *device_class; char *node_type; char *drv_name; int flags; int interpose_lvl; int (*create_callback)(di_minor_t *minor, di_node_t *node); } devfsadm_create_t; STRUCTURE ELEMENTS device_class Matches the "-c device_class" option to devfsadm(1M). This field is ignored if the device class option is not specified. Each module is free to define an arbitrary device class. ON delivered modules should document their device classes in devfsadm(1M). node_type Matches against nodetype of the minor node being processed (see ddi_create_minor_node(9f). If NULL, it is considered a match. The match can be specified as an exact match, a partial match, or a regular expression match, as specified in the "flags" element. TYPE_EXACT is the default value. drv_name Matchs against the driver name exporting the minor node being processed. If NULL, it is considered a match. The match can be specified as an exact match or a regular expression match, as specified by in the "flags" element. DRV_EXACT is the default value. flags Specifies the match algorithm for node_type and drv_name. This value can be specified as a logical OR of single TYPE_ and single DRV_ flags. TYPE_EXACT - match node_type exactly (strcmp) TYPE_PARTIAL - match node_type partially (strncmp) TYPE_RE - match node_type using regex(3c) format regular expression. DRV_EXACT - match drv_name exactly (strcmp) DRV_RE - match drv_name using regex(3c) format regular expression. interpose_lvl It is possible that multiple devfsadm_create structures will match a given minor node. Each matching structure's callback will be called in order of "interpose_lvl". Thus, a higher priority callback can return DEVFSADM_TERMINATE and prevent lower priority callbacks from executing. Devfsadm examines all devfsadm_create structures until either a callback function returns DEVFSADM_TERMINATE or all structures have been examined. create_callback Callback function to invoke if all matches are successful. For a complete definition of this function, see section 4.4. STRUCTURE INITIALIZATION A loadable module must statically initialize an array of one or more devfsadm_create_t structures and supply this array as the argument to the create_table initialization macro, DEVFSADM_CREATE_INIT_V0. This macro initalizes a secondary structure (_devfsadm_create_reg) which contains the version, size, and address of the module's create callback table. The initializer macro DEVFSADM_CREATE_INIT_V0 requires that the the devfsadm_create_t structure is a statically initialized array and that all entries in the array be properly initialized. typedef struct _devfsadm_create_reg { uint_t version; uint_t count; /* number of node type registration */ /* structures */ devfsadm_create_t *tblp; } _devfsadm_create_reg_t; #define DEVFSADM_CREATE_INIT_V0(tbl) \ _devfsadm_create_reg_t _devfsadm_create_reg = { \ DEVFSADM_V0, \ (sizeof (tbl) / sizeof (devfsadm_create_t)), \ ((devfsadm_create_t *)(tbl)) } b) devfsadm_remove_t - Link Removal Registration NAME devfsadm_remove_t - devfsadm(1M) logical link processing specification SYNOPSIS #include DESCRIPTION typedef struct devfsadm_remove { char *device_class; char *dev_dirs_re; int flags; int interpose_lvl; void (*callback_fcn)(char *logical_link); } devfsadm_remove_t; STRUCTURE ELEMENTS device_class Matches the "-c device_class" option to devfsadm(1M). This field is ignored if the device class option is not specified. Each module is free to define an arbitrary device class. ON delivered modules should document their device classes in devfsadm(1M). dev_dirs_re String containing a regular expression which matches the names in /dev to be checked if dangling. flags Specifies under what conditions to invoke the callback if a dangling node matches the dev_dirs_re regular expression. This value can be specified as a logical OR of one or more flag values. Command Mode Only RM_PRE - Remove dangling links and nodes before executing any create callbacks. RM_POST - Remove dangling links and nodes after executing create callbacks. RM_ALWAYS - Always call this callback, ignoring the absense of the devfsadm(1M) cleanup (-C) flag. Daemon Mode Only RM_HOT - Remove links and minor node upon notification of hot removal. Please refer to section 4.3.1 for a more complete description of command mode vs. daemon mode removal behavior. interpose_lvl Devfsadm executes removal callbacks in decending order of interpose level. If a module removes the dangling link, the search will terminate since the link has been removed. remove_callback Callback function to invoke to remove the link. If the module developer simply wants to remove both the logical link and the physical node path, the devfsadm(1M) provided function devfsadm_rm_all() can be supplied as the removal callback function. See section 4.5 for a more complete description of this function. STRUCTURE INITIALIZATION A loadable module must statically initialize an array of one or more devfsadm_remove_t structures and pass this array as the argument to the create_table initialization macro, DEVFSADM_REMOVE_INIT_V0. This macro initalizes a secondary structure (_devfsadm_remove_reg) which contains the version, size, and address of the module's removal callback table. The initializer macro DEVFSADM_REMOVE_INIT_V0 requires that the the devfsadm_remove_t structure is a statically initialized array and that all entries in the array be properly initialized. typedef struct _devfsadm_remove_reg { uint_t version; uint_t count; devfsadm_remove_t *tblp; } _devfsadm_remove_reg_t; #define DEVFSADM_REMOVE_INIT_V0(tbl)\ _devfsadm_remove_reg_t _devfsadm_remove_reg = {\ DEVFSADM_V0, \ (sizeof (tbl) / sizeof (devfsadm_remove_t)), \ ((devfsadm_remove_t *)(tbl)) } Command Mode Removal Behavior In command line mode, remove registration structures are examined before and after creating new logical links. If the devfsadm(1M) cleanup flag -C was not specified, only remove registration structures that specify RM_ALWAYS and either RM_PRE or RE_POST will be considered further. If the -C cleanup flag was given, but the class flag -c was not specified, module callbacks which have flags set to RM_PRE or RE_POST will be considered further, without regard to the RM_ALWAYS flag. If -C and -c were given, the device_class element must match a device class given on the command line, and if either RM_PRE or RE_POST is set, the remove structure is considered further. The following cleanup matrix shows under what conditions devfsadm(1M) will examine nodes for possible cleanup. The first column specifies the combinations of -C and -c on the command line, and the next four columns specify given combinations of devfsadm_remove_t flag values. A "-" indicates no cleanup, while "pre-clean" means attempt cleanup before creating new logical links, and "post-clean" means attempt cleanup after creating new logical links. Cleanup matrix for command mode devsadm(1M) ------------------------------------------- command line arguments RM_PRE RM_POST RM_PRE && RM_POST && RM_ALWAYS RM_ALWAYS ---------------------- ------ ----- ----------- ------------ - - pre-clean post-clean -C pre-clean post-clean pre-clean post-clean -C -c class pre-clean post-clean pre-clean post-clean if class if class if class if class matches matches matches matches -c class - - pre-clean post-clean if class if class matches matches c) Loadable Module Callback Functions NAME int create_callback(di_node_t devnode, di_minor_t minornode) DESCRIPTION A module's create_callback() is invoked by devfsadm(1M) whenever a minor node it is currently processing satisfies the matching criteria associated in the callback registration (see section 4.2). The callback function is provided handles to the devinfo node and minor node data, allowing the callback to access any of the data that is associated with the minor device via libdevinfo. The create_callback function typically constructs the logical device name from data supplied by the minor node and commits the link to the /dev namespace by calling devfsadm_mklink(). Note: The module developer must take precautions to insure the callbacks are coded MT-safe and only utilize MT safe libraries. ARGUMENTS devnode Handle to the devinfo node exporting the minor node being processed. (see libdevinfo, PSARC/1997/127) minornode Handle to the minor node being processed. RETURN VALUE DEVFSADM_CONTINUE Continue calling create_callback() functions whose selection criteria match "minornode" DEVFSADM_TERMINATE Complete the processing of this node without calling any further callbacks. d) Loadable Module Callback Functions NAME void remove_callback(char *devpath) DESCRIPTION A module's remove_callback() is invoked by devfsadm(1M) when it encounters a dangling logical link whose name matches the matching criteria associated in the callback registration (see section 4.3). The function is passed the dangling logical link relative to /dev. If the module developer simply wants to remove both the logical link and the physical node path, the devfsadm(1M) supplied function devfsadm_rm_all() can be supplied as the removal callback function. The callback function must use devfsadm_rm_link() or devfsadm_rm_all to remove links or device special files. This allows the devfsadm(1M) -n flag processing to report which links would be removed without actually removing them. Note: The module developer must take precautions to ensure the callbacks are coded MT-safe, along with only utilizing MT-safe libraries. ARGUMENTS devpath String containing the danging logical link name. RETURN VALUES none e) devfsadm_mklink - Create logical device links NAME int devfsadm_mklink(char *logical_node, di_node_t *node, di_minor_t *minor, int flags); int devfsadm_secondary_link(char *logical_node, char *primary_node, int flags); DESCRIPTION devfsadm_mklink is used by link creation callback functions to create logical links in /dev that refer to /devices entries. ARGUMENTS logical_node Name to add to the /dev namespace. logical_node is relative to the dev directory. node The di_node_t value passed to the create function. minor The di_minor_t value passed to the create function. primary_node In the case of creating a secondary link, this is the contents of the secondary link. flags DEV_SYNC Create the link synchronous with the call. Return DEVFSADM_FAILURE if the link already exists. RETURN VALUES DEVFSADM_SUCCESS - Link creation was successful DEVFSADM_FAILURE - Link creation failed NOTES If the -n flag was given on the command line, devfsadm(1M) will not create the link. With both -n and -v specified, devfsadm_mklink will report the action it would have taken if -n had not been specified. f) devfsadm_rm_all(), devfsadm_rm_link() NAME void devfsadm_rm_all(char *link); void devfsadm_rm_link(char *link); DESCRIPTION devfsadm_rm_all() must be used by removal callback functions to remove the logical name in /dev along with the device special file in /devices. This function can serve as the removal callback function itself for most cases. devfsadm_rm_link() removes only the link passed as the argument. ARGUMENTS link Name of logical link in /dev to remove. NOTES If the -n flag was given on the command line, devfsadm(1M) will not remove any links. With both -n and -v, devfsadm(1M) reports the action it would have taken had -n not been specified. g) devfsadm_print() NAME void devfsadm_print(char *msgid, char *format, [arg, ...]) DESCRIPTION devfsadm_print() provides selective printing capabilities for the loadable modules. Messages are printed to the process' stdout if executing in command mode or logged to syslogd(1M) when operating in daemon mode. Loadable modules must call devfsadm_print() if they wish to print informational or debug messages. Whether devfsadm_print() produces any output is governed by the msgid string, along with the -V and -v options passed on the command line to devfsadm. If msgid matches one of the strings passed in the argument of the -V option, data will be output on stdout, otherwise this function does nothing. If the -v option is used, printing will occur if the print function passed VERBOSE_MID in msgid. Module developers will be encouraged to prefix the msgid with the module name to prevent collisions, along with any string suffix to identify the particular print, or set of print statements. For modules which don't require any further division for different print statements, the module name without any suffix will be sufficient for the msgid. Two special defines will be available to module developers in devfsadm.h, to be passed in the msgid argument: VERBOSE_MID: printing is desired when the published -v (verbose) option is used. The devfsadm project would like to restrict verbosity printing in the context of "-v" to only print out state changes, such as adding, removing, or modifying a link or a minor node. INFO_MID: printing is desired always, without regard to -v or the -V options. ARGUMENTS msgid a string value which must match a devfsadm -V argument for this function to print. format printf(3s) style format string. args Optional data to be printed under the control of the format string. h) devfsadm_errprint() - Error reporting NAME void devfsadm_errprint(char *message, ...) DESCRIPTION devfsadm_errprint() provides error logging capabilities for loadable modules. Error messages are always printed to the user's terminal if executing in command mode or logged to syslogd(1M) when operating in daemon mode. Loadable modules must call devfsadm_errprint() rather than calling devfsadm_print() if they encounter unexpected failures during processing. ARGUMENTS format printf(3s) style format string. args Optional data to be printed under the control of the format string. i) devfsadm_root_path() - return current root update path NAME const char * devfsadm_root_path(void) DESCRIPTION Return current root update path ARGUMENTS void RETURN "/" if root_dir[0] == NULL root_dir - otherwise 13. SUPPLIER and CONSUMER agree that changes to the INTERFACES will be tested as follows: CONSUMER will work with VERITAS to verify the compatibility of these changes in a timely manner. Any breakage resulted from these changes will be corrected through the normal bug fixing process. 14. SUPPLIER and CONSUMER agree that this contract can be terminated as follows: Terminate upon mutual agreement. 15. This contract is not valid until "signed" via agreement from the SUPPLIER and CONSUMER, and approved by the ARC CASE referenced by this contract. E-mail agreement to the contract should be archived in the mail archive of CASE; verbal agreement to the contract should be noted in the meeting minutes. This contract remains valid until superseded or invalidated. For SUPPLIER: Cindy Sabenorio Date: For CONSUMER: Ravi Srinivasan Date: For ARC: Shudong Zhou Date: A copy of this contract shall be deposited in the CASE directory as "contract-1" or in a "contracts" subdirectory. An e-mail alias "contract-????-???-ss@sun.com" shall be created via netadmin for notification of any desired changes. The SUPPLIER shall be the alias owner. 16. (Not to be filled in until superseded or invalidated.) This contract was superseded or invalidated by CASE: For ARC: Date: ------------------------------------------- The old contract has been renamed to contract-01.old -- mark --Boundary_(ID_CbFLhOcH09OSGLc/F4tqPA) Content-type: text/html; charset=ISO-8859-1 Content-transfer-encoding: 7BIT 
This email amends http://sac.sfbay/PSARC/2002/421/contract-01
to cover Veritas's use of  "devfsadm_root_path".

The updated contract is in the case directory.

CHANGES:

Update the "CONSUMER" to the current team.

Product or Bundle:            VERITAS Volume Manager / Veritas Storage Foundation (which included VxVM)
 Consolidation:                N/A
 Department or Group:          Business Partner Software Engineering (BPSE)
 Bugtraq Category/SubCategory: nws_veritas_storage_foundation
 Responsible Manager:          Denise.Vitt@Sun.com
 Email alias for team:         vmfs-pde@sun.com



Add to section 4  "The INTERFACES":



On the "Devfsadm Loadable Module INTERFACES" table need to add row:



| devfsadm_root_path    |   Sun Private  |  return current root update path |




In section 2  "The SUPPLIER (definer and/or implementor) is
identified by the following"
 It already reference "Product or Bundle"   Solaris 9+ 
I'd like to ensure it means Solaris 10 too.   Could this be changed
to says Solaris 9, 10, and11 or OpenSolaris

Emails  from  Veritas development engineering - prasanna_narayana@symantec.com  Engineering Manager:
For a zones solution, VxVM started using devfsadm plugin(a private interface) to create device nodes

- We are building our source with a private copy of devfsadm.h(from opensolaris) as the header file is not
publicly available to create our own devfs dynamic .so library.
- The plugin uses the following devfs calls :

devfsadm_root_path
devfsadm_mklink
devfsadm_rm_all
- It links with libdevinfo

Could you make sure that you will put some sort of agreement to notify if the above changes ?
 
NEW CONTRACT:
--------------------------
         CONTRACT FOR CONTRACT PRIVATE INTERFACES
 
 0. Number: PSARC/2002/421
 
 
 1. This contract is between a SUPPLIER of INTERFACES and a CONSUMER of
 those INTERFACES, both of whom are entities within Sun Microsystems,
 Incorporated.
 
 2. The SUPPLIER (definer and/or implementor) is identified by the    
 following: 
 Product or Bundle:            Solaris 9, 10, and greater
 Consolidation:                ON
 Department or Group:          Solaris I/O Group
 Bugtraq Category/SubCategory: Kernel/devfs
 Responsible Manager:          Cindy Sabenorio

 
 3. The CONSUMER is identified by the following:
 Product or Bundle:            VERITAS Volume Manager (aka Veritas Storage Foundation)
 Consolidation:                N/A
 Department or Group:          Business Partner Software Engineering (BPSE)
 Bugtraq Category/SubCategory: nws_veritas_storage_foundation/vxvm, sevm/vxvm
 Responsible Manager:          Denise Vitt
 Department Alias:             vmfs-pde@sun.com

 4. The INTERFACES are: 

  Libdevinfo devlinks INTERFACE:
  ==============================
   a) di_devlink_handle_t di_devlink_init(const char *drv, uint_t flags);
   b) int di_devlink_fini(di_devlink_handle_t *pp);
   c) DI_MAKE_LINK

+----------------------------------------------------------------------------+
| Devfsadm Loadable Module INTERFACES:                                       |
| ====================================                                       |
|                                                                            |
| devfsadm_create_t              | Sun Private | callback reg. structure     |
| TYPE_{EXACT, RE, PARTIAL}      | Sun Private | minor nodetype match        |
| DRV_{EXACT, RE}                | Sun Private | driver name match criteria  |
| ILEVEL_0                       | Sun Private | callback interpose level    |
| int (*create_callback)()       | Sun Private | minor create callback fcn   |
| DEVFSADM_CREATE_INIT_V0        | Sun Private | registration initializer    |
| devfsadm_remove_t              | Sun Private | callback reg. structure     |
| int (*remove_callback)()       | Sun Private | link removal callback fcn.  |
| RM_{HOT, PRE, POST, ALWAYS}    | Sun Private | remove callback reg. flags  |
| DEVFSADM_REMOVE_INIT_V0        | Sun Private | registration initializer    |
| DEVFSADM_{SUCCESS, FAILURE}    | Sun Private | return values               |
| DEVFSADM_{TRUE, FALSE}         | Sun Private | return values               |
| DEVFSADM_{CONTINUE, TERMINATE} | Sun Private | callback return value       |
| devfsadm_mklink()              | Sun Private | Create logical link         |
| devfsadm_rm_all()              | Sun Private | remove logical link / nodes |
| devfsadm_rm_link()             | Sun Private | remove link                 |
| devfsadm_print()               | Sun Private | printing function           |
| devfsadm_errprint()            | Sun Private | error reporting             |
| VERBOSE_MID                    | Sun Private | used in devfsadm_print      |
| INFO_MID                       | Sun Private | used in devfsadm_print      |
| devfsadm_root_path()           | Sun Private | current root update path    | 
+----------------------------------------------------------------------------+


 5. The ARC controlling these INTERFACES is:

 PSARC
 
 6. The CASE describing these INTERFACES are:

 PSARC/2000/310,
 PSARC/2002/239, and
 PSARC/1997/202, 1998/275, 1998/416 and 1999/473

 7b. Although the stability level doesn't normally allow it, CONSUMER
 will expose INTERFACES to a PARTNER, which is external to Sun, namely:

      Name of Company:       VERITAS Software Corporation
      Department or Group:   VERITAS Volume Manager Development Team
      Responsible Manager:   Umesh Toprani

 7d. Changes to INTERFACES requires ARC approval.  If SUPPLIER decides to
 change (including replace or remove) any portion of the INTERFACES,
 SUPPLIER will notify CONSUMER of the proposed new version, no later
 than the application for ARC approval of the new version.  If SUPPLIER
 and CONSUMER are contained in the same bundle, they have the option of
 arranging for simultaneous conversion to the new interfaces.  If this
 is not possible, or if they are not in the same bundle, then SUPPLIER
 will either make best effort to work with CONSUMER so that CONSUMER can
 detect which version of INTERFACES is being supplied, or else SUPPLIER
 will make best effort to supply both old and new versions of
 INTERFACES.  If SUPPLIER cannot make both versions of INTERFACES
 available, and SUPPLIER and CONSUMER cannot devise a method whereby
 CONSUMER can detect which version of INTERFACES is being supplied, and
 the old version of CONSUMER will not run with the new version of
 SUPPLIER, then either the EOL process must be followed by SUPPLIER, or
 else a major release of SUPPLIER will be required.
 
 [Note not in contract.  To protect against mismatches in contract
 private interfaces between non-co-bundled components, such interfaces
 must include adequate versioning provisions to deal with reasonably
 anticipatable changes.  The release number returned by uname -r will in
 some cases be sufficient to determine which version of a
 Solaris-bundled interface exists.]
 
 8. If CONSUMER requires changes in INTERFACES, SUPPLIER will make best
 effort to accommodate such changes, which shall then be treated in
 accordance with paragraph 7 above.
 
 9. Notwithstanding paragraphs 7 and 8, a change to any portion of the
 INTERFACES shall be regarded as a completely new set of INTERFACES, and
 requires execution of a new contract.
 
 10. SUPPLIER and CONSUMER agree that evolution of INTERFACES shall be
 handled as follows:

 Proposed changes will be reviewed by BPSE and VERITAS Volume Manager
 Development Team.

 11. SUPPLIER and CONSUMER agree that INTERFACES will be supported as
 follows:

 The INTERFACES will be maintained on Sun SPARC platforms that VERITAS
 Volume Manager 3.5 and higher runs on.  VERITAS will deploy the 
 INTERFACES on Solaris 9 and above.

 SUPPLIER and CONSUMER will report problems through Bugtraq.
 
 12. SUPPLIER and CONSUMER agree that INTERFACES will be documented as
 follows:

LIBDEVINFO DEVLINKS INTERFACES:
-------------------------------
SYNOPSIS
        #include <libdevinfo.h>

	di_devlink_handle_t di_devlink_init(const char *name, uint_t flags);

	int di_devlink_fini(di_devlink_handle_t *hdlp);

DESCRIPTION
	di_devlink_init() takes a snapshot of devlinks and returns a
	handle to this snapshot. di_devlink_fini() destroys the snapshot
	and frees the associated memory.


a) di_devlink_handle_t di_devlink_init(const char *name, uint_t flags);

   ARGUMENTS
        flags   Currently the following flags are supported:
                DI_MAKE_LINK    Create devlinks to reflect current state of the
                                kernel device tree before taking the snapshot.
                                Use of this flag requires superuser permissions.

	name	If flags is DI_MAKE_LINK, name specifies the set of minors
		for which devlinks are to be created. A NULL value selects all
		minors on the system. If flags is 0, the first argument should
		be NULL.

		name can be one of the following:
		-	driver name
		-	physical path to the root of a subtree (without
			/devices prefix)


   RETURN VALUES
    di_devlink_init()
        On success, a handle to the snapshot is returned. Otherwise, NULL
        is returned and errno is set to indicate the error.

   ERRORS
    di_devlink_init()
        EINVAL          invalid argument(s)
        ENOMEM          insufficient memory

        With the DI_MAKE_LINK flag, the following may also be returned:
        EPERM           not superuser

b) int di_devlink_fini(di_devlink_handle_t *pp);

   ARGUMENTS
        pp    Pointer to a handle to the snapshot.

   RETURN VALUES
    di_devlink_fini()
        Upon success, 0 is returned. Otherwise, -1 is returned and errno
        is set to indicate the error.

   ERRORS
    di_devlink_fini()
        EINVAL          invalid snapshot handle.


DEVFSADM LOADABLE MODULE INTERFACES:
------------------------------------

 a) devfsadm_create_t - Link Creation Registration
 
 NAME
     devfsadm_create_t - devfsadm(1M) logical link processing specification. 
 
 SYNOPSIS
     #include <devfsadm.h>
 
     Loadable modules may register one or more link creation
     callback functions with devfsadm(1M) by statically initializing a
     table of devfsadm_create_t structures, specifying the matching
     criteria that are used by devfsadm(1M) to select which callbacks to invoke.
 
 DESCRIPTION
 
     typedef struct devfsadm_create {
             char    *device_class;
             char    *node_type;
             char    *drv_name;
             int     flags;
             int     interpose_lvl;
             int     (*create_callback)(di_minor_t *minor, di_node_t *node);
     } devfsadm_create_t;
 
     
 STRUCTURE ELEMENTS
 
     device_class    Matches the "-c device_class" option to devfsadm(1M).
                     This field is ignored if the device class option is
                     not specified. Each module is free to define an
                     arbitrary device class.  ON delivered modules should
                     document their device classes in devfsadm(1M). 
     
     node_type       Matches against nodetype of the minor node being
                     processed (see ddi_create_minor_node(9f). If NULL, it
                     is considered a match.  The match can be specified 
                     as an exact match, a partial match, or a regular
                     expression match, as specified in the "flags" element.
                     TYPE_EXACT is the default value.
 
     drv_name        Matchs against the driver name exporting the
                     minor node being processed.  If NULL, it is considered
                     a match.  The match can be specified as an exact
                     match or a regular expression match, as specified by
                     in the "flags" element.  DRV_EXACT is the default value.
 
     flags           Specifies the match algorithm for node_type and
                     drv_name. This value can be specified as a
                     logical OR of single TYPE_ and single DRV_ flags.
 
                     TYPE_EXACT      - match node_type exactly (strcmp)
                     TYPE_PARTIAL    - match node_type partially (strncmp)
                     TYPE_RE         - match node_type using regex(3c)
                                       format regular expression.
                     DRV_EXACT       - match drv_name exactly (strcmp)
                     DRV_RE          - match drv_name using regex(3c)
                                       format regular expression.
 
     interpose_lvl   It is possible that multiple devfsadm_create structures
                     will match a given minor node.  Each matching structure's
                     callback will be called in order of "interpose_lvl". 
                     Thus, a higher priority callback can return
                     DEVFSADM_TERMINATE and prevent lower priority callbacks
                     from executing.
 
                     Devfsadm examines all devfsadm_create structures until
                     either a callback function returns DEVFSADM_TERMINATE or
                     all structures have been examined.
 
     create_callback Callback function to invoke if all matches are
                     successful.  For a complete definition of this
                     function, see section 4.4.
 
 
 STRUCTURE INITIALIZATION
 
     A loadable module must statically initialize an array of one or
     more devfsadm_create_t structures and supply this array as the
     argument to the create_table initialization macro,
     DEVFSADM_CREATE_INIT_V0.  This macro initalizes a secondary structure
     (_devfsadm_create_reg) which contains the version, size, and address of
     the module's create callback table.
 
     The initializer macro DEVFSADM_CREATE_INIT_V0 requires that the
     the devfsadm_create_t structure is a statically initialized
     array and that all entries in the array be properly initialized.
 
     typedef struct _devfsadm_create_reg {
             uint_t version;
             uint_t count;   /* number of node type registration */
                             /* structures */
             devfsadm_create_t *tblp;
     } _devfsadm_create_reg_t;
 
     #define DEVFSADM_CREATE_INIT_V0(tbl) \
             _devfsadm_create_reg_t _devfsadm_create_reg = { \
             DEVFSADM_V0, \
             (sizeof (tbl) / sizeof (devfsadm_create_t)), \
             ((devfsadm_create_t *)(tbl)) }
 
 
 
 b) devfsadm_remove_t - Link Removal Registration 
 
 NAME
     devfsadm_remove_t - devfsadm(1M) logical link processing specification
 
 SYNOPSIS
     #include <devfsadm.h>
 
 
 DESCRIPTION
 
     typedef struct devfsadm_remove {
             char    *device_class;
             char    *dev_dirs_re;
             int     flags;
             int     interpose_lvl;
             void (*callback_fcn)(char *logical_link);
     } devfsadm_remove_t;
 
 
 STRUCTURE ELEMENTS
 
     device_class    Matches the "-c device_class" option to devfsadm(1M).
                     This field is ignored if the device class option is
                     not specified. Each module is free to define an
                     arbitrary device class.  ON delivered modules should
                     document their device classes in devfsadm(1M). 
     
     dev_dirs_re     String containing a regular expression which matches
                     the names in /dev to be checked if dangling.
 
     flags           Specifies under what conditions to invoke the callback
                     if a dangling node matches the dev_dirs_re regular
                     expression.  This value can be specified as a
                     logical OR of one or more flag values.
 
                     Command Mode Only
 
                     RM_PRE          - Remove dangling links and nodes before
                                       executing any create callbacks.
                     RM_POST         - Remove dangling links and nodes after
                                       executing create callbacks.
 
                     RM_ALWAYS       - Always call this callback, ignoring
                                       the absense of the devfsadm(1M)
                                       cleanup (-C) flag.
 
                     Daemon Mode Only
 
                     RM_HOT          - Remove links and minor node upon
                                       notification of hot removal.
 
                     Please refer to section 4.3.1 for a more complete
                     description of command mode vs. daemon mode
                     removal behavior.
 
 
     interpose_lvl   Devfsadm executes removal callbacks in decending
                     order of interpose level.  If a module removes
                     the dangling link, the search will terminate since
                     the link has been removed.
 
     remove_callback Callback function to invoke to remove the link.  If the
                     module developer simply wants to remove both the logical
                     link and the physical node path, the devfsadm(1M) provided
                     function devfsadm_rm_all() can be supplied as the removal
                     callback function.  See section 4.5 for a more complete
                     description of this function.
 
     
 STRUCTURE INITIALIZATION
 
     A loadable module must statically initialize an array of one or
     more devfsadm_remove_t structures and pass this array as the
     argument to the create_table initialization macro,
     DEVFSADM_REMOVE_INIT_V0.  This macro initalizes a secondary
     structure (_devfsadm_remove_reg) which contains the version, size,
     and address of the module's removal callback table.
 
     The initializer macro DEVFSADM_REMOVE_INIT_V0 requires that the
     the devfsadm_remove_t structure is a statically initialized
     array and that all entries in the array be properly initialized.
 
     typedef struct _devfsadm_remove_reg {
             uint_t version;
             uint_t count;   
             devfsadm_remove_t *tblp;
     } _devfsadm_remove_reg_t;
 
     #define DEVFSADM_REMOVE_INIT_V0(tbl)\
             _devfsadm_remove_reg_t _devfsadm_remove_reg = {\
             DEVFSADM_V0, \
             (sizeof (tbl) / sizeof (devfsadm_remove_t)), \
             ((devfsadm_remove_t *)(tbl)) }
 
 
 
 Command Mode Removal Behavior
 
 In command line mode, remove registration structures are examined
 before and after creating new logical links. If the devfsadm(1M) cleanup
 flag -C was not specified, only remove registration structures that
 specify RM_ALWAYS and either RM_PRE or RE_POST will be considered further.
 
 If the -C cleanup flag was given, but the class flag -c was not
 specified, module callbacks which have flags set to RM_PRE or RE_POST
 will be considered further, without regard to the RM_ALWAYS flag. 
 
 If -C and -c were given, the device_class element must match a device class
 given on the command line, and if either RM_PRE or RE_POST is set, the
 remove structure is considered further.
 
 The following cleanup matrix shows under what conditions devfsadm(1M)
 will examine nodes for possible cleanup.  The first column
 specifies the combinations of -C and -c on the command line, and the
 next four columns specify given combinations of devfsadm_remove_t flag
 values.  A "-" indicates no cleanup, while "pre-clean" means attempt cleanup
 before creating new logical links, and "post-clean" means attempt
 cleanup after creating new logical links.
 
 
             Cleanup matrix for command mode devsadm(1M)
             -------------------------------------------
 
 command line arguments  RM_PRE    RM_POST       RM_PRE &&      RM_POST &&
                                                 RM_ALWAYS      RM_ALWAYS
 ----------------------  ------     -----        -----------    ------------
 
 <neither -c or -C>      -         -             pre-clean       post-clean
 
 -C                      pre-clean  post-clean   pre-clean       post-clean
 
 -C -c class             pre-clean  post-clean   pre-clean       post-clean
                         if class   if class     if class        if class
                         matches    matches      matches         matches
 
 -c class                 -           -          pre-clean       post-clean
                                                if class         if class
                                                matches         matches
 
 
 c) Loadable Module Callback Functions
 
 NAME
     int create_callback(di_node_t devnode, di_minor_t minornode)
 
     
 DESCRIPTION
 
     A module's create_callback() is invoked by devfsadm(1M)
     whenever a minor node it is currently processing satisfies
     the matching criteria associated in the callback registration
     (see section 4.2). The callback function is provided handles to
     the devinfo node and minor node data, allowing the callback to 
     access any of the data that is associated with the minor device
     via libdevinfo.
 
     The create_callback function typically constructs 
     the logical device name from data supplied by the
     minor node and commits the link to the /dev namespace by
     calling devfsadm_mklink().
 
     Note: The module developer must take precautions to insure the
     callbacks are coded MT-safe and only utilize MT safe
     libraries.
 
 ARGUMENTS
 
     devnode         Handle to the devinfo node exporting the minor
                     node being processed.
                     (see libdevinfo, PSARC/1997/127)
 
     minornode       Handle to the minor node being processed.
 
 
 RETURN VALUE
 
     DEVFSADM_CONTINUE       Continue calling create_callback()
                             functions whose selection criteria
                             match "minornode"
 
     DEVFSADM_TERMINATE      Complete the processing of this
                             node without calling any further
                             callbacks.
                             
 
 d)  Loadable Module Callback Functions
 
 NAME
     void remove_callback(char *devpath)
 
     
 DESCRIPTION
 
     A module's remove_callback() is invoked by devfsadm(1M) when it
     encounters a dangling logical link whose name matches the
     matching criteria associated in the callback registration
     (see section 4.3).
             
     The function is passed the dangling logical link relative to /dev.
 
     If the module developer simply wants to remove both the logical
     link and the physical node path, the devfsadm(1M) supplied function
     devfsadm_rm_all() can be supplied as the removal callback function.
 
     The callback function must use devfsadm_rm_link() or devfsadm_rm_all to
     remove links or device special files.  This allows the devfsadm(1M) -n
     flag processing to report which links would be removed without actually
     removing them.
 
     Note: The module developer must take precautions to ensure the
     callbacks are coded MT-safe, along with only utilizing MT-safe
     libraries.
 
 ARGUMENTS
 
     devpath         String containing the danging logical link
                     name.
 
 RETURN VALUES
 
     none
 
 
 e)  devfsadm_mklink - Create logical device links
 
 NAME
     int devfsadm_mklink(char *logical_node, di_node_t *node, di_minor_t *minor,
                             int flags);
     int devfsadm_secondary_link(char *logical_node, char *primary_node, int flags);
 
 DESCRIPTION
 
     devfsadm_mklink is used by link creation callback functions to 
     create logical links in /dev that refer to /devices entries.
 
 
 ARGUMENTS
 
     logical_node    Name to add to the /dev namespace.
                     logical_node is relative to the dev directory.
 
     node            The di_node_t value passed to the create function.
 
     minor           The di_minor_t value passed to the create function.
 
     primary_node    In the case of creating a secondary link, this is the
                     contents of the secondary link.
                     
     flags           DEV_SYNC
                     Create the link synchronous with the call. Return
                     DEVFSADM_FAILURE if the link already exists.
 
 
 RETURN VALUES
 
     DEVFSADM_SUCCESS        - Link creation was successful
     DEVFSADM_FAILURE        - Link creation failed
     
 NOTES
     If the -n flag was given on the command line, devfsadm(1M) will not create
     the link.  With both -n and -v specified, devfsadm_mklink will report
     the action it would have taken if -n had not been specified.
 
 
 
 f)  devfsadm_rm_all(), devfsadm_rm_link()
 
 NAME
     void devfsadm_rm_all(char *link);
     void devfsadm_rm_link(char *link);
 
 DESCRIPTION
 
     devfsadm_rm_all() must be used by removal callback
     functions to remove the logical name in /dev along with the device
     special file in /devices.  This function can serve as the
     removal callback function itself for most cases.
 
     devfsadm_rm_link() removes only the link passed as the argument.
     
 ARGUMENTS
 
     link            Name of logical link in /dev to remove.
 
 
 NOTES
     If the -n flag was given on the command line, devfsadm(1M) will not remove
     any links.  With both -n and -v, devfsadm(1M) reports the action it
     would have taken had -n not been specified.
 
 
 g)  devfsadm_print()        
 
 NAME
     void devfsadm_print(char *msgid, char *format, [arg, ...])
 
 
 DESCRIPTION
 
     devfsadm_print() provides selective printing capabilities for
     the loadable modules.  Messages are printed to the process' stdout
     if executing in command mode or logged to syslogd(1M) when 
     operating in daemon mode.
 
     Loadable modules must call devfsadm_print() if they wish
     to print informational or debug messages.

     Whether devfsadm_print() produces any output is governed by the
     msgid string, along with the -V and -v options passed on the
     command line to devfsadm.  If msgid matches one of the strings
     passed in the argument of the -V option, data will be output on
     stdout, otherwise this function does nothing.  If the -v option
     is used, printing will occur if the print function passed VERBOSE_MID
     in msgid.

     Module developers will be encouraged to prefix the msgid with the module
     name to prevent collisions, along with any string suffix to identify
     the particular print, or set of print statements.  For modules which
     don't require any further division for different print statements, the
     module name without any suffix will be sufficient for the msgid.

     Two special defines will be available to module developers in
     devfsadm.h, to be passed in the msgid argument:

     VERBOSE_MID:  printing is desired when the published -v (verbose) option
                   is used.  The devfsadm project would like to restrict verbosity
                   printing in the context of "-v" to only print out state changes,
                   such as adding, removing, or modifying a link or a minor node.

     INFO_MID:     printing is desired always, without regard to -v or the -V
                   options.



 ARGUMENTS

     msgid   a string value which must match a devfsadm -V argument for
             this function to print.
 
     format  printf(3s) style format string.
 
     args    Optional data to be printed under the control of the
             format string.
     
 
     
 h)  devfsadm_errprint() - Error reporting
 
 NAME
     void devfsadm_errprint(char *message, ...)
 
 
 DESCRIPTION
 
     devfsadm_errprint() provides error logging capabilities for
     loadable modules.  Error messages are always printed to the
     user's terminal if executing in command mode or logged to
     syslogd(1M) when operating in daemon mode.
 
     Loadable modules must call devfsadm_errprint() rather
     than calling devfsadm_print() if they encounter unexpected
     failures during processing.
     
 ARGUMENTS
 
     format  printf(3s) style format string.
 
     args    Optional data to be printed under the control of the
             format string.

 i)  devfsadm_root_path() - return current root update path

 NAME
   const char * devfsadm_root_path(void)

 DESCRIPTION
    
     Return current root update path 

 ARGUMENTS
   
     void

 RETURN

     "/" if root_dir[0] == NULL
     root_dir - otherwise

     
    

 13. SUPPLIER and CONSUMER agree that changes to the INTERFACES will be
 tested as follows:

 CONSUMER will work with VERITAS to verify the compatibility of
 these changes in a timely manner.  Any breakage resulted from
 these changes will be corrected through the normal bug fixing
 process.
 
 14. SUPPLIER and CONSUMER agree that this contract can be terminated as
 follows:

 Terminate upon mutual agreement.

 15. This contract is not valid until "signed" via agreement from the
 SUPPLIER and CONSUMER, and approved by the ARC CASE referenced by this
 contract.  E-mail agreement to the contract should be archived in the
 mail archive of CASE; verbal agreement to the contract should be noted
 in the meeting minutes.  This contract remains valid until superseded
 or invalidated.
 
 For SUPPLIER: Cindy Sabenorio   Date: 
 For CONSUMER: Ravi Srinivasan   Date: 
 For ARC: Shudong Zhou		 Date: 
 
 A copy of this contract shall be deposited in the CASE directory as
 "contract-1" or in a "contracts" subdirectory.
 
 An e-mail alias "contract-????-???-ss@sun.com" shall be created via
 netadmin for notification of any desired changes. The SUPPLIER shall be
 the alias owner.
 
 16. (Not to be filled in until superseded or invalidated.)
 This contract was superseded or invalidated by CASE:
 For ARC:                        Date:
-------------------------------------------

The old contract has been renamed to contract-01.old

-- mark
--Boundary_(ID_CbFLhOcH09OSGLc/F4tqPA)--