Debian Codegraph @

doc/doxygen-doc/html/a00171.html

raw
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): Converting between Object Types and Attributes, and Strings</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">&#160;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="#func-members">Functions</a> </div>
47 <div class="headertitle"><div class="title">Converting between Object Types and Attributes, and Strings </div></div>
48 </div><!--header-->
49 <div class="contents">
50 <table class="memberdecls">
51 <tr class="heading"><td colspan="2"><h2 id="header-func-members" class="groupheader"><a id="func-members" name="func-members"></a>
52 Functions</h2></td></tr>
53 <tr class="memitem:ga6a38b931e5d45e8af4323a169482fe39" id="r_ga6a38b931e5d45e8af4323a169482fe39"><td class="memItemLeft" align="right" valign="top">const char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga6a38b931e5d45e8af4323a169482fe39">hwloc_obj_type_string</a> (<a class="el" href="a00167.html#gacd37bb612667dc437d66bfb175a8dc55">hwloc_obj_type_t</a> type)</td></tr>
54 <tr class="memitem:gadb8765c260edea80c52cd06a76639ba4" id="r_gadb8765c260edea80c52cd06a76639ba4"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gadb8765c260edea80c52cd06a76639ba4">hwloc_obj_type_snprintf</a> (char *restrict string, size_t size, <a class="el" href="a00168.html#ga79b8ab56877ef99ac59b833203391c7d">hwloc_obj_t</a> obj, int verbose)</td></tr>
55 <tr class="memitem:ga870e876931c282a1c7aee2f031912ce3" id="r_ga870e876931c282a1c7aee2f031912ce3"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga870e876931c282a1c7aee2f031912ce3">hwloc_obj_attr_snprintf</a> (char *restrict string, size_t size, <a class="el" href="a00168.html#ga79b8ab56877ef99ac59b833203391c7d">hwloc_obj_t</a> obj, const char *restrict separator, int verbose)</td></tr>
56 <tr class="memitem:ga510f21b066fba2dab12b8c9b173b1dfd" id="r_ga510f21b066fba2dab12b8c9b173b1dfd"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga510f21b066fba2dab12b8c9b173b1dfd">hwloc_type_sscanf</a> (const char *string, <a class="el" href="a00167.html#gacd37bb612667dc437d66bfb175a8dc55">hwloc_obj_type_t</a> *typep, union <a class="el" href="a00228.html">hwloc_obj_attr_u</a> *attrp, size_t attrsize)</td></tr>
57 <tr class="memitem:ga52c63cd7203e55b804c1314affc9bd12" id="r_ga52c63cd7203e55b804c1314affc9bd12"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga52c63cd7203e55b804c1314affc9bd12">hwloc_type_sscanf_as_depth</a> (const char *string, <a class="el" href="a00167.html#gacd37bb612667dc437d66bfb175a8dc55">hwloc_obj_type_t</a> *typep, <a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, int *depthp)</td></tr>
58 </table>
59 <a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2>
60 <a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2>
61 <a id="ga870e876931c282a1c7aee2f031912ce3" name="ga870e876931c282a1c7aee2f031912ce3"></a>
62 <h2 class="memtitle"><span class="permalink"><a href="#ga870e876931c282a1c7aee2f031912ce3">&#9670;&#160;</a></span>hwloc_obj_attr_snprintf()</h2>
63
64 <div class="memitem">
65 <div class="memproto">
66 <table class="memname">
67 <tr>
68 <td class="memname">int hwloc_obj_attr_snprintf </td>
69 <td>(</td>
70 <td class="paramtype">char *restrict</td> <td class="paramname"><span class="paramname"><em>string</em></span>, </td>
71 </tr>
72 <tr>
73 <td class="paramkey"></td>
74 <td></td>
75 <td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>size</em></span>, </td>
76 </tr>
77 <tr>
78 <td class="paramkey"></td>
79 <td></td>
80 <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>
81 </tr>
82 <tr>
83 <td class="paramkey"></td>
84 <td></td>
85 <td class="paramtype">const char *restrict</td> <td class="paramname"><span class="paramname"><em>separator</em></span>, </td>
86 </tr>
87 <tr>
88 <td class="paramkey"></td>
89 <td></td>
90 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>verbose</em></span>&#160;)</td>
91 </tr>
92 </table>
93 </div><div class="memdoc">
94
95 <p>Stringify the attributes of a given topology object into a human-readable form. </p>
96 <p>Attribute values are separated by <code class="param">separator</code>.</p>
97 <p>Only the major attributes are printed in non-verbose mode.</p>
98 <p>If <code class="param">size</code> is 0, <code class="param">string</code> may safely be <code>NULL</code>.</p>
99 <dl class="section return"><dt>Returns</dt><dd>the number of characters that were actually written if not truncating, or that would have been written (not including the ending <code>\0</code>). </dd></dl>
100
101 </div>
102 </div>
103 <a id="gadb8765c260edea80c52cd06a76639ba4" name="gadb8765c260edea80c52cd06a76639ba4"></a>
104 <h2 class="memtitle"><span class="permalink"><a href="#gadb8765c260edea80c52cd06a76639ba4">&#9670;&#160;</a></span>hwloc_obj_type_snprintf()</h2>
105
106 <div class="memitem">
107 <div class="memproto">
108 <table class="memname">
109 <tr>
110 <td class="memname">int hwloc_obj_type_snprintf </td>
111 <td>(</td>
112 <td class="paramtype">char *restrict</td> <td class="paramname"><span class="paramname"><em>string</em></span>, </td>
113 </tr>
114 <tr>
115 <td class="paramkey"></td>
116 <td></td>
117 <td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>size</em></span>, </td>
118 </tr>
119 <tr>
120 <td class="paramkey"></td>
121 <td></td>
122 <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>
123 </tr>
124 <tr>
125 <td class="paramkey"></td>
126 <td></td>
127 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>verbose</em></span>&#160;)</td>
128 </tr>
129 </table>
130 </div><div class="memdoc">
131
132 <p>Stringify the type of a given topology object into a human-readable form. </p>
133 <p>Contrary to <a class="el" href="#ga6a38b931e5d45e8af4323a169482fe39" title="Return a constant stringified object type.">hwloc_obj_type_string()</a>, this function includes object-specific attributes (such as the Group depth, the Bridge type, or OS device type) in the output, and it requires the caller to provide the output buffer.</p>
134 <p>The output is guaranteed to be the same for all objects of a same topology level.</p>
135 <p>If <code class="param">verbose</code> is 1, longer type names are used, e.g. L1Cache instead of L1.</p>
136 <p>The output string may be parsed back by <a class="el" href="#ga510f21b066fba2dab12b8c9b173b1dfd" title="Return an object type and attributes from a type string.">hwloc_type_sscanf()</a>.</p>
137 <p>If <code class="param">size</code> is 0, <code class="param">string</code> may safely be <code>NULL</code>.</p>
138 <dl class="section return"><dt>Returns</dt><dd>the number of characters that were actually written if not truncating, or that would have been written (not including the ending <code>\0</code>). </dd></dl>
139
140 </div>
141 </div>
142 <a id="ga6a38b931e5d45e8af4323a169482fe39" name="ga6a38b931e5d45e8af4323a169482fe39"></a>
143 <h2 class="memtitle"><span class="permalink"><a href="#ga6a38b931e5d45e8af4323a169482fe39">&#9670;&#160;</a></span>hwloc_obj_type_string()</h2>
144
145 <div class="memitem">
146 <div class="memproto">
147 <table class="memname">
148 <tr>
149 <td class="memname">const char * hwloc_obj_type_string </td>
150 <td>(</td>
151 <td class="paramtype"><a class="el" href="a00167.html#gacd37bb612667dc437d66bfb175a8dc55">hwloc_obj_type_t</a></td> <td class="paramname"><span class="paramname"><em>type</em></span></td><td>)</td>
152 <td></td>
153 </tr>
154 </table>
155 </div><div class="memdoc">
156
157 <p>Return a constant stringified object type. </p>
158 <p>This function is the basic way to convert a generic type into a string. The output string may be parsed back by <a class="el" href="#ga510f21b066fba2dab12b8c9b173b1dfd" title="Return an object type and attributes from a type string.">hwloc_type_sscanf()</a>.</p>
159 <p><a class="el" href="#gadb8765c260edea80c52cd06a76639ba4" title="Stringify the type of a given topology object into a human-readable form.">hwloc_obj_type_snprintf()</a> may return a more precise output for a specific object, but it requires the caller to provide the output buffer.</p>
160 <dl class="section return"><dt>Returns</dt><dd>A constant string containing the object type name or <code>"Unknown"</code>. </dd></dl>
161
162 </div>
163 </div>
164 <a id="ga510f21b066fba2dab12b8c9b173b1dfd" name="ga510f21b066fba2dab12b8c9b173b1dfd"></a>
165 <h2 class="memtitle"><span class="permalink"><a href="#ga510f21b066fba2dab12b8c9b173b1dfd">&#9670;&#160;</a></span>hwloc_type_sscanf()</h2>
166
167 <div class="memitem">
168 <div class="memproto">
169 <table class="memname">
170 <tr>
171 <td class="memname">int hwloc_type_sscanf </td>
172 <td>(</td>
173 <td class="paramtype">const char *</td> <td class="paramname"><span class="paramname"><em>string</em></span>, </td>
174 </tr>
175 <tr>
176 <td class="paramkey"></td>
177 <td></td>
178 <td class="paramtype"><a class="el" href="a00167.html#gacd37bb612667dc437d66bfb175a8dc55">hwloc_obj_type_t</a> *</td> <td class="paramname"><span class="paramname"><em>typep</em></span>, </td>
179 </tr>
180 <tr>
181 <td class="paramkey"></td>
182 <td></td>
183 <td class="paramtype">union <a class="el" href="a00228.html">hwloc_obj_attr_u</a> *</td> <td class="paramname"><span class="paramname"><em>attrp</em></span>, </td>
184 </tr>
185 <tr>
186 <td class="paramkey"></td>
187 <td></td>
188 <td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>attrsize</em></span>&#160;)</td>
189 </tr>
190 </table>
191 </div><div class="memdoc">
192
193 <p>Return an object type and attributes from a type string. </p>
194 <p>Convert strings such as "Package" or "L1iCache" into the corresponding types. Matching is case-insensitive, and only the first letters are actually required to match.</p>
195 <p>The matched object type is set in <code class="param">typep</code> (which cannot be <code>NULL</code>).</p>
196 <p>Type-specific attributes, for instance Cache type, Cache depth, Group depth, Bridge type or OS Device type may be returned in <code class="param">attrp</code>. Attributes that are not specified in the string (for instance "Group" without a depth, or "L2Cache" without a cache type) are set to -1.</p>
197 <p><code class="param">attrp</code> is only filled if not <code>NULL</code> and if its size specified in <code class="param">attrsize</code> is large enough. It should be at least as large as union <a class="el" href="a00228.html" title="Object type-specific Attributes.">hwloc_obj_attr_u</a>.</p>
198 <dl class="section return"><dt>Returns</dt><dd>0 if a type was correctly identified, otherwise -1.</dd></dl>
199 <dl class="section note"><dt>Note</dt><dd>This function is guaranteed to match any string returned by <a class="el" href="#ga6a38b931e5d45e8af4323a169482fe39" title="Return a constant stringified object type.">hwloc_obj_type_string()</a> or <a class="el" href="#gadb8765c260edea80c52cd06a76639ba4" title="Stringify the type of a given topology object into a human-readable form.">hwloc_obj_type_snprintf()</a>.</dd>
200 <dd>
201 This is an extended version of the now deprecated hwloc_obj_type_sscanf(). </dd></dl>
202
203 </div>
204 </div>
205 <a id="ga52c63cd7203e55b804c1314affc9bd12" name="ga52c63cd7203e55b804c1314affc9bd12"></a>
206 <h2 class="memtitle"><span class="permalink"><a href="#ga52c63cd7203e55b804c1314affc9bd12">&#9670;&#160;</a></span>hwloc_type_sscanf_as_depth()</h2>
207
208 <div class="memitem">
209 <div class="memproto">
210 <table class="memname">
211 <tr>
212 <td class="memname">int hwloc_type_sscanf_as_depth </td>
213 <td>(</td>
214 <td class="paramtype">const char *</td> <td class="paramname"><span class="paramname"><em>string</em></span>, </td>
215 </tr>
216 <tr>
217 <td class="paramkey"></td>
218 <td></td>
219 <td class="paramtype"><a class="el" href="a00167.html#gacd37bb612667dc437d66bfb175a8dc55">hwloc_obj_type_t</a> *</td> <td class="paramname"><span class="paramname"><em>typep</em></span>, </td>
220 </tr>
221 <tr>
222 <td class="paramkey"></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">int *</td> <td class="paramname"><span class="paramname"><em>depthp</em></span>&#160;)</td>
230 </tr>
231 </table>
232 </div><div class="memdoc">
233
234 <p>Return an object type and its level depth from a type string. </p>
235 <p>Convert strings such as "Package" or "L1iCache" into the corresponding types and return in <code class="param">depthp</code> the depth of the corresponding level in the topology <code class="param">topology</code>.</p>
236 <p>If no object of this type is present on the underlying architecture, <a class="el" href="a00170.html#ggaf4e663cf42bbe20756b849c6293ef575a0565ab92ab72cb0cec91e23003294aad" title="No object of given type exists in the topology.">HWLOC_TYPE_DEPTH_UNKNOWN</a> is returned.</p>
237 <p>If multiple such levels exist (for instance if giving Group without any depth), the function may return <a class="el" href="a00170.html#ggaf4e663cf42bbe20756b849c6293ef575ae99465995cacde6c210d5fc2e409798c" title="Objects of given type exist at different depth in the topology (only for Groups).">HWLOC_TYPE_DEPTH_MULTIPLE</a> instead.</p>
238 <p>The matched object type is set in <code class="param">typep</code> if <code class="param">typep</code> is non <code>NULL</code>.</p>
239 <dl class="section note"><dt>Note</dt><dd>This function is similar to <a class="el" href="#ga510f21b066fba2dab12b8c9b173b1dfd" title="Return an object type and attributes from a type string.">hwloc_type_sscanf()</a> followed by <a class="el" href="a00170.html#ga8bec782e21be313750da70cf7428b374" title="Returns the depth of objects of type type.">hwloc_get_type_depth()</a> but it also automatically disambiguates multiple group levels etc.</dd>
240 <dd>
241 This function is guaranteed to match any string returned by <a class="el" href="#ga6a38b931e5d45e8af4323a169482fe39" title="Return a constant stringified object type.">hwloc_obj_type_string()</a> or <a class="el" href="#gadb8765c260edea80c52cd06a76639ba4" title="Stringify the type of a given topology object into a human-readable form.">hwloc_obj_type_snprintf()</a>. </dd></dl>
242
243 </div>
244 </div>
245 </div><!-- contents -->
246 <!-- start footer part -->
247 <hr class="footer"/><address class="footer"><small>
248 Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.15.0
249 </small></address>
250 </div><!-- doc-content -->
251 </body>
252 </html>