| 1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 2 |
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US"> |
| 3 |
<head> |
| 4 |
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> |
| 5 |
<meta http-equiv="X-UA-Compatible" content="IE=11"/> |
| 6 |
<meta name="generator" content="Doxygen 1.15.0"/> |
| 7 |
<meta name="viewport" content="width=device-width, initial-scale=1"/> |
| 8 |
<title>Hardware Locality (hwloc): Exporting Topologies to XML</title> |
| 9 |
<link href="tabs.css" rel="stylesheet" type="text/css"/> |
| 10 |
<script type="text/javascript" src="jquery.js"></script> |
| 11 |
<script type="text/javascript" src="dynsections.js"></script> |
| 12 |
<script type="text/javascript" src="clipboard.js"></script> |
| 13 |
<link href="doxygen.css" rel="stylesheet" type="text/css" /> |
| 14 |
</head> |
| 15 |
<body> |
| 16 |
<div id="top"><!-- do not remove this div, it is closed by doxygen! --> |
| 17 |
<div id="titlearea"> |
| 18 |
<table cellspacing="0" cellpadding="0"> |
| 19 |
<tbody> |
| 20 |
<tr id="projectrow"> |
| 21 |
<td id="projectalign"> |
| 22 |
<div id="projectname">Hardware Locality (hwloc)<span id="projectnumber"> 2.14.0</span> |
| 23 |
</div> |
| 24 |
</td> |
| 25 |
</tr> |
| 26 |
</tbody> |
| 27 |
</table> |
| 28 |
</div> |
| 29 |
<!-- end header part --> |
| 30 |
<!-- Generated by Doxygen 1.15.0 --> |
| 31 |
<script type="text/javascript"> |
| 32 |
$(function() { codefold.init(); }); |
| 33 |
</script> |
| 34 |
<script type="text/javascript" src="menudata.js"></script> |
| 35 |
<script type="text/javascript" src="menu.js"></script> |
| 36 |
<script type="text/javascript"> |
| 37 |
$(function() { |
| 38 |
initMenu('',false,false,'search.php','Search',false); |
| 39 |
}); |
| 40 |
</script> |
| 41 |
<div id="main-nav"></div> |
| 42 |
</div><!-- top --> |
| 43 |
<div id="doc-content"> |
| 44 |
<div class="header"> |
| 45 |
<div class="summary"> |
| 46 |
<a href="#enum-members">Enumerations</a> | |
| 47 |
<a href="#func-members">Functions</a> </div> |
| 48 |
<div class="headertitle"><div class="title">Exporting Topologies to XML </div></div> |
| 49 |
</div><!--header--> |
| 50 |
<div class="contents"> |
| 51 |
<table class="memberdecls"> |
| 52 |
<tr class="heading"><td colspan="2"><h2 id="header-enum-members" class="groupheader"><a id="enum-members" name="enum-members"></a> |
| 53 |
Enumerations</h2></td></tr> |
| 54 |
<tr class="memitem:ga0eb99636aff71fe2704e1fa0ffe8c18d" id="r_ga0eb99636aff71fe2704e1fa0ffe8c18d"><td class="memItemLeft" align="right" valign="top">enum  </td><td class="memItemRight" valign="bottom"><a class="el" href="#ga0eb99636aff71fe2704e1fa0ffe8c18d">hwloc_topology_export_xml_flags_e</a> { <a class="el" href="#gga0eb99636aff71fe2704e1fa0ffe8c18dae7d6d96546131ef0043867b836b02e0f">HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1</a> |
| 55 |
}</td></tr> |
| 56 |
</table><table class="memberdecls"> |
| 57 |
<tr class="heading"><td colspan="2"><h2 id="header-func-members" class="groupheader"><a id="func-members" name="func-members"></a> |
| 58 |
Functions</h2></td></tr> |
| 59 |
<tr class="memitem:ga333f79975b4eeb28a3d8fad3373583ce" id="r_ga333f79975b4eeb28a3d8fad3373583ce"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="#ga333f79975b4eeb28a3d8fad3373583ce">hwloc_topology_export_xml</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, const char *xmlpath, unsigned long flags)</td></tr> |
| 60 |
<tr class="memitem:gad33b7f7c11db10459505a3b1634fd3f1" id="r_gad33b7f7c11db10459505a3b1634fd3f1"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="#gad33b7f7c11db10459505a3b1634fd3f1">hwloc_topology_export_xmlbuffer</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, char **xmlbuffer, int *buflen, unsigned long flags)</td></tr> |
| 61 |
<tr class="memitem:ga293e4a6489f15fd16ad22a5734561cf1" id="r_ga293e4a6489f15fd16ad22a5734561cf1"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#ga293e4a6489f15fd16ad22a5734561cf1">hwloc_free_xmlbuffer</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, char *xmlbuffer)</td></tr> |
| 62 |
<tr class="memitem:ga9d6ff0f7a8dd45be9aa8575ef31978cc" id="r_ga9d6ff0f7a8dd45be9aa8575ef31978cc"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#ga9d6ff0f7a8dd45be9aa8575ef31978cc">hwloc_topology_set_userdata_export_callback</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, void(*export_cb)(void *reserved, <a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="a00168.html#ga79b8ab56877ef99ac59b833203391c7d">hwloc_obj_t</a> obj))</td></tr> |
| 63 |
<tr class="memitem:gaa541bdd628416dbbe97d0df69d3de958" id="r_gaa541bdd628416dbbe97d0df69d3de958"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="#gaa541bdd628416dbbe97d0df69d3de958">hwloc_export_obj_userdata</a> (void *reserved, <a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="a00168.html#ga79b8ab56877ef99ac59b833203391c7d">hwloc_obj_t</a> obj, const char *name, const void *buffer, size_t length)</td></tr> |
| 64 |
<tr class="memitem:ga1b7358137cec27bd073f58a606ecbaba" id="r_ga1b7358137cec27bd073f58a606ecbaba"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="#ga1b7358137cec27bd073f58a606ecbaba">hwloc_export_obj_userdata_base64</a> (void *reserved, <a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="a00168.html#ga79b8ab56877ef99ac59b833203391c7d">hwloc_obj_t</a> obj, const char *name, const void *buffer, size_t length)</td></tr> |
| 65 |
<tr class="memitem:ga5ac6917ea7289955fb1ffda4353af9b0" id="r_ga5ac6917ea7289955fb1ffda4353af9b0"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="#ga5ac6917ea7289955fb1ffda4353af9b0">hwloc_topology_set_userdata_import_callback</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, void(*import_cb)(<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="a00168.html#ga79b8ab56877ef99ac59b833203391c7d">hwloc_obj_t</a> obj, const char *name, const void *buffer, size_t length))</td></tr> |
| 66 |
</table> |
| 67 |
<a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2> |
| 68 |
<a name="doc-enum-members" id="doc-enum-members"></a><h2 id="header-doc-enum-members" class="groupheader">Enumeration Type Documentation</h2> |
| 69 |
<a id="ga0eb99636aff71fe2704e1fa0ffe8c18d" name="ga0eb99636aff71fe2704e1fa0ffe8c18d"></a> |
| 70 |
<h2 class="memtitle"><span class="permalink"><a href="#ga0eb99636aff71fe2704e1fa0ffe8c18d">◆ </a></span>hwloc_topology_export_xml_flags_e</h2> |
| 71 |
|
| 72 |
<div class="memitem"> |
| 73 |
<div class="memproto"> |
| 74 |
<table class="memname"> |
| 75 |
<tr> |
| 76 |
<td class="memname">enum <a class="el" href="#ga0eb99636aff71fe2704e1fa0ffe8c18d">hwloc_topology_export_xml_flags_e</a></td> |
| 77 |
</tr> |
| 78 |
</table> |
| 79 |
</div><div class="memdoc"> |
| 80 |
|
| 81 |
<p>Flags for exporting XML topologies. </p> |
| 82 |
<p>Flags to be given as a OR'ed set to <a class="el" href="#ga333f79975b4eeb28a3d8fad3373583ce" title="Export the topology into an XML file.">hwloc_topology_export_xml()</a>. </p> |
| 83 |
<table class="fieldtable"> |
| 84 |
<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="gga0eb99636aff71fe2704e1fa0ffe8c18dae7d6d96546131ef0043867b836b02e0f" name="gga0eb99636aff71fe2704e1fa0ffe8c18dae7d6d96546131ef0043867b836b02e0f"></a>HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 </td><td class="fielddoc"><p>Export XML that is loadable by hwloc v1.x. However, the export may miss some details about the topology. </p> |
| 85 |
</td></tr> |
| 86 |
</table> |
| 87 |
|
| 88 |
</div> |
| 89 |
</div> |
| 90 |
<a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2> |
| 91 |
<a id="gaa541bdd628416dbbe97d0df69d3de958" name="gaa541bdd628416dbbe97d0df69d3de958"></a> |
| 92 |
<h2 class="memtitle"><span class="permalink"><a href="#gaa541bdd628416dbbe97d0df69d3de958">◆ </a></span>hwloc_export_obj_userdata()</h2> |
| 93 |
|
| 94 |
<div class="memitem"> |
| 95 |
<div class="memproto"> |
| 96 |
<table class="memname"> |
| 97 |
<tr> |
| 98 |
<td class="memname">int hwloc_export_obj_userdata </td> |
| 99 |
<td>(</td> |
| 100 |
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>reserved</em></span>, </td> |
| 101 |
</tr> |
| 102 |
<tr> |
| 103 |
<td class="paramkey"></td> |
| 104 |
<td></td> |
| 105 |
<td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td> |
| 106 |
</tr> |
| 107 |
<tr> |
| 108 |
<td class="paramkey"></td> |
| 109 |
<td></td> |
| 110 |
<td class="paramtype"><a class="el" href="a00168.html#ga79b8ab56877ef99ac59b833203391c7d">hwloc_obj_t</a></td> <td class="paramname"><span class="paramname"><em>obj</em></span>, </td> |
| 111 |
</tr> |
| 112 |
<tr> |
| 113 |
<td class="paramkey"></td> |
| 114 |
<td></td> |
| 115 |
<td class="paramtype">const char *</td> <td class="paramname"><span class="paramname"><em>name</em></span>, </td> |
| 116 |
</tr> |
| 117 |
<tr> |
| 118 |
<td class="paramkey"></td> |
| 119 |
<td></td> |
| 120 |
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td> |
| 121 |
</tr> |
| 122 |
<tr> |
| 123 |
<td class="paramkey"></td> |
| 124 |
<td></td> |
| 125 |
<td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td> |
| 126 |
</tr> |
| 127 |
</table> |
| 128 |
</div><div class="memdoc"> |
| 129 |
|
| 130 |
<p>Export some object userdata to XML. </p> |
| 131 |
<p>This function may only be called from within the export() callback passed to <a class="el" href="#ga9d6ff0f7a8dd45be9aa8575ef31978cc" title="Set the application-specific callback for exporting object userdata.">hwloc_topology_set_userdata_export_callback()</a>. It may be invoked one of multiple times to export some userdata to XML. The <code class="param">buffer</code> content of length <code class="param">length</code> is stored with optional name <code class="param">name</code>.</p> |
| 132 |
<p>When importing this XML file, the import() callback (if set) will be called exactly as many times as <a class="el" href="#gaa541bdd628416dbbe97d0df69d3de958" title="Export some object userdata to XML.">hwloc_export_obj_userdata()</a> was called during export(). It will receive the corresponding <code class="param">name</code>, <code class="param">buffer</code> and <code class="param">length</code> arguments.</p> |
| 133 |
<p><code class="param">reserved</code>, <code class="param">topology</code> and <code class="param">obj</code> must be the first three parameters that were given to the export callback.</p> |
| 134 |
<p>Only printable characters may be exported to XML string attributes.</p> |
| 135 |
<p>If exporting binary data, the application should first encode into printable characters only (or use <a class="el" href="#ga1b7358137cec27bd073f58a606ecbaba" title="Encode and export some object userdata to XML.">hwloc_export_obj_userdata_base64()</a>). It should also take care of portability issues if the export may be reimported on a different architecture.</p> |
| 136 |
<dl class="section return"><dt>Returns</dt><dd>0 on success. </dd> |
| 137 |
<dd> |
| 138 |
-1 with errno set to <code>EINVAL</code> if a non-printable character is passed in <code class="param">name</code> or <b>buffer</b>. </dd></dl> |
| 139 |
|
| 140 |
</div> |
| 141 |
</div> |
| 142 |
<a id="ga1b7358137cec27bd073f58a606ecbaba" name="ga1b7358137cec27bd073f58a606ecbaba"></a> |
| 143 |
<h2 class="memtitle"><span class="permalink"><a href="#ga1b7358137cec27bd073f58a606ecbaba">◆ </a></span>hwloc_export_obj_userdata_base64()</h2> |
| 144 |
|
| 145 |
<div class="memitem"> |
| 146 |
<div class="memproto"> |
| 147 |
<table class="memname"> |
| 148 |
<tr> |
| 149 |
<td class="memname">int hwloc_export_obj_userdata_base64 </td> |
| 150 |
<td>(</td> |
| 151 |
<td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>reserved</em></span>, </td> |
| 152 |
</tr> |
| 153 |
<tr> |
| 154 |
<td class="paramkey"></td> |
| 155 |
<td></td> |
| 156 |
<td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td> |
| 157 |
</tr> |
| 158 |
<tr> |
| 159 |
<td class="paramkey"></td> |
| 160 |
<td></td> |
| 161 |
<td class="paramtype"><a class="el" href="a00168.html#ga79b8ab56877ef99ac59b833203391c7d">hwloc_obj_t</a></td> <td class="paramname"><span class="paramname"><em>obj</em></span>, </td> |
| 162 |
</tr> |
| 163 |
<tr> |
| 164 |
<td class="paramkey"></td> |
| 165 |
<td></td> |
| 166 |
<td class="paramtype">const char *</td> <td class="paramname"><span class="paramname"><em>name</em></span>, </td> |
| 167 |
</tr> |
| 168 |
<tr> |
| 169 |
<td class="paramkey"></td> |
| 170 |
<td></td> |
| 171 |
<td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td> |
| 172 |
</tr> |
| 173 |
<tr> |
| 174 |
<td class="paramkey"></td> |
| 175 |
<td></td> |
| 176 |
<td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>length</em></span> )</td> |
| 177 |
</tr> |
| 178 |
</table> |
| 179 |
</div><div class="memdoc"> |
| 180 |
|
| 181 |
<p>Encode and export some object userdata to XML. </p> |
| 182 |
<p>This function is similar to <a class="el" href="#gaa541bdd628416dbbe97d0df69d3de958" title="Export some object userdata to XML.">hwloc_export_obj_userdata()</a> but it encodes the input buffer into printable characters before exporting. On import, decoding is automatically performed before the data is given to the import() callback if any.</p> |
| 183 |
<p>This function may only be called from within the export() callback passed to <a class="el" href="#ga9d6ff0f7a8dd45be9aa8575ef31978cc" title="Set the application-specific callback for exporting object userdata.">hwloc_topology_set_userdata_export_callback()</a>.</p> |
| 184 |
<p>The name must be made of printable characters for export to XML string attributes.</p> |
| 185 |
<p>The function does not take care of portability issues if the export may be reimported on a different architecture.</p> |
| 186 |
<dl class="section return"><dt>Returns</dt><dd>0 on success. </dd> |
| 187 |
<dd> |
| 188 |
-1 with errno set to <code>EINVAL</code> if a non-printable character is passed in <code class="param">name</code>. </dd></dl> |
| 189 |
|
| 190 |
</div> |
| 191 |
</div> |
| 192 |
<a id="ga293e4a6489f15fd16ad22a5734561cf1" name="ga293e4a6489f15fd16ad22a5734561cf1"></a> |
| 193 |
<h2 class="memtitle"><span class="permalink"><a href="#ga293e4a6489f15fd16ad22a5734561cf1">◆ </a></span>hwloc_free_xmlbuffer()</h2> |
| 194 |
|
| 195 |
<div class="memitem"> |
| 196 |
<div class="memproto"> |
| 197 |
<table class="memname"> |
| 198 |
<tr> |
| 199 |
<td class="memname">void hwloc_free_xmlbuffer </td> |
| 200 |
<td>(</td> |
| 201 |
<td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td> |
| 202 |
</tr> |
| 203 |
<tr> |
| 204 |
<td class="paramkey"></td> |
| 205 |
<td></td> |
| 206 |
<td class="paramtype">char *</td> <td class="paramname"><span class="paramname"><em>xmlbuffer</em></span> )</td> |
| 207 |
</tr> |
| 208 |
</table> |
| 209 |
</div><div class="memdoc"> |
| 210 |
|
| 211 |
<p>Free a buffer allocated by <a class="el" href="#gad33b7f7c11db10459505a3b1634fd3f1" title="Export the topology into a newly-allocated XML memory buffer.">hwloc_topology_export_xmlbuffer()</a>. </p> |
| 212 |
|
| 213 |
</div> |
| 214 |
</div> |
| 215 |
<a id="ga333f79975b4eeb28a3d8fad3373583ce" name="ga333f79975b4eeb28a3d8fad3373583ce"></a> |
| 216 |
<h2 class="memtitle"><span class="permalink"><a href="#ga333f79975b4eeb28a3d8fad3373583ce">◆ </a></span>hwloc_topology_export_xml()</h2> |
| 217 |
|
| 218 |
<div class="memitem"> |
| 219 |
<div class="memproto"> |
| 220 |
<table class="memname"> |
| 221 |
<tr> |
| 222 |
<td class="memname">int hwloc_topology_export_xml </td> |
| 223 |
<td>(</td> |
| 224 |
<td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td> |
| 225 |
</tr> |
| 226 |
<tr> |
| 227 |
<td class="paramkey"></td> |
| 228 |
<td></td> |
| 229 |
<td class="paramtype">const char *</td> <td class="paramname"><span class="paramname"><em>xmlpath</em></span>, </td> |
| 230 |
</tr> |
| 231 |
<tr> |
| 232 |
<td class="paramkey"></td> |
| 233 |
<td></td> |
| 234 |
<td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span> )</td> |
| 235 |
</tr> |
| 236 |
</table> |
| 237 |
</div><div class="memdoc"> |
| 238 |
|
| 239 |
<p>Export the topology into an XML file. </p> |
| 240 |
<p>This file may be loaded later through <a class="el" href="a00175.html#ga879439b7ee99407ee911b3ac64e9a25e" title="Enable XML-file based topology.">hwloc_topology_set_xml()</a>.</p> |
| 241 |
<p>By default, the latest export format is used, which means older hwloc releases (e.g. v1.x) will not be able to import it. Exporting to v1.x specific XML format is possible using flag <a class="el" href="#gga0eb99636aff71fe2704e1fa0ffe8c18dae7d6d96546131ef0043867b836b02e0f" title="Export XML that is loadable by hwloc v1.x. However, the export may miss some details about the topolo...">HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1</a> but it may miss some details about the topology. If there is any chance that the exported file may ever be imported back by a process using hwloc 1.x, one should consider detecting it at runtime and using the corresponding export format.</p> |
| 242 |
<p><code class="param">flags</code> is a OR'ed set of <a class="el" href="#ga0eb99636aff71fe2704e1fa0ffe8c18d" title="Flags for exporting XML topologies.">hwloc_topology_export_xml_flags_e</a>.</p> |
| 243 |
<dl class="section return"><dt>Returns</dt><dd>0 on success, or -1 on error.</dd></dl> |
| 244 |
<dl class="section note"><dt>Note</dt><dd>See also <a class="el" href="#ga9d6ff0f7a8dd45be9aa8575ef31978cc" title="Set the application-specific callback for exporting object userdata.">hwloc_topology_set_userdata_export_callback()</a> for exporting application-specific object userdata.</dd> |
| 245 |
<dd> |
| 246 |
The topology-specific userdata pointer is ignored when exporting to XML.</dd> |
| 247 |
<dd> |
| 248 |
Only printable characters may be exported to XML string attributes. Any other character, especially any non-ASCII character, will be silently dropped.</dd> |
| 249 |
<dd> |
| 250 |
If <code class="param">name</code> is "-", the XML output is sent to the standard output. </dd></dl> |
| 251 |
|
| 252 |
</div> |
| 253 |
</div> |
| 254 |
<a id="gad33b7f7c11db10459505a3b1634fd3f1" name="gad33b7f7c11db10459505a3b1634fd3f1"></a> |
| 255 |
<h2 class="memtitle"><span class="permalink"><a href="#gad33b7f7c11db10459505a3b1634fd3f1">◆ </a></span>hwloc_topology_export_xmlbuffer()</h2> |
| 256 |
|
| 257 |
<div class="memitem"> |
| 258 |
<div class="memproto"> |
| 259 |
<table class="memname"> |
| 260 |
<tr> |
| 261 |
<td class="memname">int hwloc_topology_export_xmlbuffer </td> |
| 262 |
<td>(</td> |
| 263 |
<td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td> |
| 264 |
</tr> |
| 265 |
<tr> |
| 266 |
<td class="paramkey"></td> |
| 267 |
<td></td> |
| 268 |
<td class="paramtype">char **</td> <td class="paramname"><span class="paramname"><em>xmlbuffer</em></span>, </td> |
| 269 |
</tr> |
| 270 |
<tr> |
| 271 |
<td class="paramkey"></td> |
| 272 |
<td></td> |
| 273 |
<td class="paramtype">int *</td> <td class="paramname"><span class="paramname"><em>buflen</em></span>, </td> |
| 274 |
</tr> |
| 275 |
<tr> |
| 276 |
<td class="paramkey"></td> |
| 277 |
<td></td> |
| 278 |
<td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span> )</td> |
| 279 |
</tr> |
| 280 |
</table> |
| 281 |
</div><div class="memdoc"> |
| 282 |
|
| 283 |
<p>Export the topology into a newly-allocated XML memory buffer. </p> |
| 284 |
<p><code class="param">xmlbuffer</code> is allocated by the callee and should be freed with <a class="el" href="#ga293e4a6489f15fd16ad22a5734561cf1" title="Free a buffer allocated by hwloc_topology_export_xmlbuffer().">hwloc_free_xmlbuffer()</a> later in the caller.</p> |
| 285 |
<p>This memory buffer may be loaded later through <a class="el" href="a00175.html#ga2745616b65595e1c1e579ecc7e461fa8" title="Enable XML based topology using a memory buffer (instead of a file, as with hwloc_topology_set_xml())...">hwloc_topology_set_xmlbuffer()</a>.</p> |
| 286 |
<p>By default, the latest export format is used, which means older hwloc releases (e.g. v1.x) will not be able to import it. Exporting to v1.x specific XML format is possible using flag <a class="el" href="#gga0eb99636aff71fe2704e1fa0ffe8c18dae7d6d96546131ef0043867b836b02e0f" title="Export XML that is loadable by hwloc v1.x. However, the export may miss some details about the topolo...">HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1</a> but it may miss some details about the topology. If there is any chance that the exported buffer may ever be imported back by a process using hwloc 1.x, one should consider detecting it at runtime and using the corresponding export format.</p> |
| 287 |
<p>The returned buffer ends with a \0 that is included in the returned length.</p> |
| 288 |
<p><code class="param">flags</code> is a OR'ed set of <a class="el" href="#ga0eb99636aff71fe2704e1fa0ffe8c18d" title="Flags for exporting XML topologies.">hwloc_topology_export_xml_flags_e</a>.</p> |
| 289 |
<dl class="section return"><dt>Returns</dt><dd>0 on success, or -1 on error.</dd></dl> |
| 290 |
<dl class="section note"><dt>Note</dt><dd>See also <a class="el" href="#ga9d6ff0f7a8dd45be9aa8575ef31978cc" title="Set the application-specific callback for exporting object userdata.">hwloc_topology_set_userdata_export_callback()</a> for exporting application-specific object userdata.</dd> |
| 291 |
<dd> |
| 292 |
The topology-specific userdata pointer is ignored when exporting to XML.</dd> |
| 293 |
<dd> |
| 294 |
Only printable characters may be exported to XML string attributes. Any other character, especially any non-ASCII character, will be silently dropped. </dd></dl> |
| 295 |
|
| 296 |
</div> |
| 297 |
</div> |
| 298 |
<a id="ga9d6ff0f7a8dd45be9aa8575ef31978cc" name="ga9d6ff0f7a8dd45be9aa8575ef31978cc"></a> |
| 299 |
<h2 class="memtitle"><span class="permalink"><a href="#ga9d6ff0f7a8dd45be9aa8575ef31978cc">◆ </a></span>hwloc_topology_set_userdata_export_callback()</h2> |
| 300 |
|
| 301 |
<div class="memitem"> |
| 302 |
<div class="memproto"> |
| 303 |
<table class="memname"> |
| 304 |
<tr> |
| 305 |
<td class="memname">void hwloc_topology_set_userdata_export_callback </td> |
| 306 |
<td>(</td> |
| 307 |
<td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td> |
| 308 |
</tr> |
| 309 |
<tr> |
| 310 |
<td class="paramkey"></td> |
| 311 |
<td></td> |
| 312 |
<td class="paramtype">void(*</td> <td class="paramname"><span class="paramname"><em>export_cb </em></span>)(void *reserved, <a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="a00168.html#ga79b8ab56877ef99ac59b833203391c7d">hwloc_obj_t</a> obj) )</td> |
| 313 |
</tr> |
| 314 |
</table> |
| 315 |
</div><div class="memdoc"> |
| 316 |
|
| 317 |
<p>Set the application-specific callback for exporting object userdata. </p> |
| 318 |
<p>The object userdata pointer is not exported to XML by default because hwloc does not know what it contains.</p> |
| 319 |
<p>This function lets applications set <code class="param">export_cb</code> to a callback function that converts this opaque userdata into an exportable string.</p> |
| 320 |
<p><code class="param">export_cb</code> is invoked during XML export for each object whose <code class="param">userdata</code> pointer is not <code>NULL</code>. The callback should use <a class="el" href="#gaa541bdd628416dbbe97d0df69d3de958" title="Export some object userdata to XML.">hwloc_export_obj_userdata()</a> or <a class="el" href="#ga1b7358137cec27bd073f58a606ecbaba" title="Encode and export some object userdata to XML.">hwloc_export_obj_userdata_base64()</a> to actually export something to XML (possibly multiple times per object).</p> |
| 321 |
<p><code class="param">export_cb</code> may be set to <code>NULL</code> if userdata should not be exported to XML.</p> |
| 322 |
<dl class="section note"><dt>Note</dt><dd>The topology-specific userdata pointer is ignored when exporting to XML. </dd></dl> |
| 323 |
|
| 324 |
</div> |
| 325 |
</div> |
| 326 |
<a id="ga5ac6917ea7289955fb1ffda4353af9b0" name="ga5ac6917ea7289955fb1ffda4353af9b0"></a> |
| 327 |
<h2 class="memtitle"><span class="permalink"><a href="#ga5ac6917ea7289955fb1ffda4353af9b0">◆ </a></span>hwloc_topology_set_userdata_import_callback()</h2> |
| 328 |
|
| 329 |
<div class="memitem"> |
| 330 |
<div class="memproto"> |
| 331 |
<table class="memname"> |
| 332 |
<tr> |
| 333 |
<td class="memname">void hwloc_topology_set_userdata_import_callback </td> |
| 334 |
<td>(</td> |
| 335 |
<td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td> |
| 336 |
</tr> |
| 337 |
<tr> |
| 338 |
<td class="paramkey"></td> |
| 339 |
<td></td> |
| 340 |
<td class="paramtype">void(*</td> <td class="paramname"><span class="paramname"><em>import_cb </em></span>)(<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="a00168.html#ga79b8ab56877ef99ac59b833203391c7d">hwloc_obj_t</a> obj, const char *name, const void *buffer, size_t length) )</td> |
| 341 |
</tr> |
| 342 |
</table> |
| 343 |
</div><div class="memdoc"> |
| 344 |
|
| 345 |
<p>Set the application-specific callback for importing userdata. </p> |
| 346 |
<p>On XML import, userdata is ignored by default because hwloc does not know how to store it in memory.</p> |
| 347 |
<p>This function lets applications set <code class="param">import_cb</code> to a callback function that will get the XML-stored userdata and store it in the object as expected by the application.</p> |
| 348 |
<p><code class="param">import_cb</code> is called during <a class="el" href="a00169.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load()</a> as many times as <a class="el" href="#gaa541bdd628416dbbe97d0df69d3de958" title="Export some object userdata to XML.">hwloc_export_obj_userdata()</a> was called during export. The topology is not entirely setup yet. Object attributes are ready to consult, but links between objects are not.</p> |
| 349 |
<p><code class="param">import_cb</code> may be <code>NULL</code> if userdata should be ignored during import.</p> |
| 350 |
<dl class="section note"><dt>Note</dt><dd><code class="param">buffer</code> contains <code class="param">length</code> characters followed by a null byte ('\0').</dd> |
| 351 |
<dd> |
| 352 |
This function should be called before <a class="el" href="a00169.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load()</a>.</dd> |
| 353 |
<dd> |
| 354 |
The topology-specific userdata pointer is ignored when importing from XML. </dd></dl> |
| 355 |
|
| 356 |
</div> |
| 357 |
</div> |
| 358 |
</div><!-- contents --> |
| 359 |
<!-- start footer part --> |
| 360 |
<hr class="footer"/><address class="footer"><small> |
| 361 |
Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.15.0 |
| 362 |
</small></address> |
| 363 |
</div><!-- doc-content --> |
| 364 |
</body> |
| 365 |
</html> |