Debian Codegraph @

doc/doxygen-doc/man/man3/hwlocality_xmlexport.3

raw
1 .TH "hwlocality_xmlexport" 3 "Version 2.14.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 hwlocality_xmlexport \- Exporting Topologies to XML
6 .SH SYNOPSIS
7 .br
8 .PP
9 .SS "Enumerations"
10
11 .in +1c
12 .ti -1c
13 .RI "enum \fBhwloc_topology_export_xml_flags_e\fP { \fBHWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1\fP }"
14 .br
15 .in -1c
16 .SS "Functions"
17
18 .in +1c
19 .ti -1c
20 .RI "int \fBhwloc_topology_export_xml\fP (\fBhwloc_topology_t\fP topology, const char *xmlpath, unsigned long flags)"
21 .br
22 .ti -1c
23 .RI "int \fBhwloc_topology_export_xmlbuffer\fP (\fBhwloc_topology_t\fP topology, char **xmlbuffer, int *buflen, unsigned long flags)"
24 .br
25 .ti -1c
26 .RI "void \fBhwloc_free_xmlbuffer\fP (\fBhwloc_topology_t\fP topology, char *xmlbuffer)"
27 .br
28 .ti -1c
29 .RI "void \fBhwloc_topology_set_userdata_export_callback\fP (\fBhwloc_topology_t\fP topology, void(*export_cb)(void *reserved, \fBhwloc_topology_t\fP topology, \fBhwloc_obj_t\fP obj))"
30 .br
31 .ti -1c
32 .RI "int \fBhwloc_export_obj_userdata\fP (void *reserved, \fBhwloc_topology_t\fP topology, \fBhwloc_obj_t\fP obj, const char *name, const void *buffer, size_t length)"
33 .br
34 .ti -1c
35 .RI "int \fBhwloc_export_obj_userdata_base64\fP (void *reserved, \fBhwloc_topology_t\fP topology, \fBhwloc_obj_t\fP obj, const char *name, const void *buffer, size_t length)"
36 .br
37 .ti -1c
38 .RI "void \fBhwloc_topology_set_userdata_import_callback\fP (\fBhwloc_topology_t\fP topology, void(*import_cb)(\fBhwloc_topology_t\fP topology, \fBhwloc_obj_t\fP obj, const char *name, const void *buffer, size_t length))"
39 .br
40 .in -1c
41 .SH "Detailed Description"
42 .PP
43
44 .SH "Enumeration Type Documentation"
45 .PP
46 .SS "enum \fBhwloc_topology_export_xml_flags_e\fP"
47
48 .PP
49 Flags for exporting XML topologies\&. Flags to be given as a OR'ed set to \fBhwloc_topology_export_xml()\fP\&.
50 .PP
51 \fBEnumerator\fP
52 .in +1c
53 .TP
54 \f(BIHWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1 \fP
55 Export XML that is loadable by hwloc v1\&.x\&. However, the export may miss some details about the topology\&.
56 .SH "Function Documentation"
57 .PP
58 .SS "int hwloc_export_obj_userdata (void * reserved, \fBhwloc_topology_t\fP topology, \fBhwloc_obj_t\fP obj, const char * name, const void * buffer, size_t length)"
59
60 .PP
61 Export some object userdata to XML\&. This function may only be called from within the export() callback passed to \fBhwloc_topology_set_userdata_export_callback()\fP\&. It may be invoked one of multiple times to export some userdata to XML\&. The \fRbuffer\fP content of length \fRlength\fP is stored with optional name \fRname\fP\&.
62
63 .PP
64 When importing this XML file, the import() callback (if set) will be called exactly as many times as \fBhwloc_export_obj_userdata()\fP was called during export()\&. It will receive the corresponding \fRname\fP, \fRbuffer\fP and \fRlength\fP arguments\&.
65
66 .PP
67 \fRreserved\fP, \fRtopology\fP and \fRobj\fP must be the first three parameters that were given to the export callback\&.
68
69 .PP
70 Only printable characters may be exported to XML string attributes\&.
71
72 .PP
73 If exporting binary data, the application should first encode into printable characters only (or use \fBhwloc_export_obj_userdata_base64()\fP)\&. It should also take care of portability issues if the export may be reimported on a different architecture\&.
74
75 .PP
76 \fBReturns\fP
77 .RS 4
78 0 on success\&.
79
80 .PP
81 -1 with errno set to \fREINVAL\fP if a non-printable character is passed in \fRname\fP or \fBbuffer\fP\&.
82 .RE
83 .PP
84
85 .SS "int hwloc_export_obj_userdata_base64 (void * reserved, \fBhwloc_topology_t\fP topology, \fBhwloc_obj_t\fP obj, const char * name, const void * buffer, size_t length)"
86
87 .PP
88 Encode and export some object userdata to XML\&. This function is similar to \fBhwloc_export_obj_userdata()\fP 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\&.
89
90 .PP
91 This function may only be called from within the export() callback passed to \fBhwloc_topology_set_userdata_export_callback()\fP\&.
92
93 .PP
94 The name must be made of printable characters for export to XML string attributes\&.
95
96 .PP
97 The function does not take care of portability issues if the export may be reimported on a different architecture\&.
98
99 .PP
100 \fBReturns\fP
101 .RS 4
102 0 on success\&.
103
104 .PP
105 -1 with errno set to \fREINVAL\fP if a non-printable character is passed in \fRname\fP\&.
106 .RE
107 .PP
108
109 .SS "void hwloc_free_xmlbuffer (\fBhwloc_topology_t\fP topology, char * xmlbuffer)"
110
111 .PP
112 Free a buffer allocated by \fBhwloc_topology_export_xmlbuffer()\fP\&.
113 .SS "int hwloc_topology_export_xml (\fBhwloc_topology_t\fP topology, const char * xmlpath, unsigned long flags)"
114
115 .PP
116 Export the topology into an XML file\&. This file may be loaded later through \fBhwloc_topology_set_xml()\fP\&.
117
118 .PP
119 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 \fBHWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1\fP 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\&.
120
121 .PP
122 \fRflags\fP is a OR'ed set of \fBhwloc_topology_export_xml_flags_e\fP\&.
123
124 .PP
125 \fBReturns\fP
126 .RS 4
127 0 on success, or -1 on error\&.
128 .RE
129 .PP
130 \fBNote\fP
131 .RS 4
132 See also \fBhwloc_topology_set_userdata_export_callback()\fP for exporting application-specific object userdata\&.
133
134 .PP
135 The topology-specific userdata pointer is ignored when exporting to XML\&.
136
137 .PP
138 Only printable characters may be exported to XML string attributes\&. Any other character, especially any non-ASCII character, will be silently dropped\&.
139
140 .PP
141 If \fRname\fP is "-", the XML output is sent to the standard output\&.
142 .RE
143 .PP
144
145 .SS "int hwloc_topology_export_xmlbuffer (\fBhwloc_topology_t\fP topology, char ** xmlbuffer, int * buflen, unsigned long flags)"
146
147 .PP
148 Export the topology into a newly-allocated XML memory buffer\&. \fRxmlbuffer\fP is allocated by the callee and should be freed with \fBhwloc_free_xmlbuffer()\fP later in the caller\&.
149
150 .PP
151 This memory buffer may be loaded later through \fBhwloc_topology_set_xmlbuffer()\fP\&.
152
153 .PP
154 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 \fBHWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1\fP 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\&.
155
156 .PP
157 The returned buffer ends with a \\0 that is included in the returned length\&.
158
159 .PP
160 \fRflags\fP is a OR'ed set of \fBhwloc_topology_export_xml_flags_e\fP\&.
161
162 .PP
163 \fBReturns\fP
164 .RS 4
165 0 on success, or -1 on error\&.
166 .RE
167 .PP
168 \fBNote\fP
169 .RS 4
170 See also \fBhwloc_topology_set_userdata_export_callback()\fP for exporting application-specific object userdata\&.
171
172 .PP
173 The topology-specific userdata pointer is ignored when exporting to XML\&.
174
175 .PP
176 Only printable characters may be exported to XML string attributes\&. Any other character, especially any non-ASCII character, will be silently dropped\&.
177 .RE
178 .PP
179
180 .SS "void hwloc_topology_set_userdata_export_callback (\fBhwloc_topology_t\fP topology, void(* export_cb )(void *reserved, \fBhwloc_topology_t\fP topology, \fBhwloc_obj_t\fP obj))"
181
182 .PP
183 Set the application-specific callback for exporting object userdata\&. The object userdata pointer is not exported to XML by default because hwloc does not know what it contains\&.
184
185 .PP
186 This function lets applications set \fRexport_cb\fP to a callback function that converts this opaque userdata into an exportable string\&.
187
188 .PP
189 \fRexport_cb\fP is invoked during XML export for each object whose \fRuserdata\fP pointer is not \fRNULL\fP\&. The callback should use \fBhwloc_export_obj_userdata()\fP or \fBhwloc_export_obj_userdata_base64()\fP to actually export something to XML (possibly multiple times per object)\&.
190
191 .PP
192 \fRexport_cb\fP may be set to \fRNULL\fP if userdata should not be exported to XML\&.
193
194 .PP
195 \fBNote\fP
196 .RS 4
197 The topology-specific userdata pointer is ignored when exporting to XML\&.
198 .RE
199 .PP
200
201 .SS "void hwloc_topology_set_userdata_import_callback (\fBhwloc_topology_t\fP topology, void(* import_cb )(\fBhwloc_topology_t\fP topology, \fBhwloc_obj_t\fP obj, const char *name, const void *buffer, size_t length))"
202
203 .PP
204 Set the application-specific callback for importing userdata\&. On XML import, userdata is ignored by default because hwloc does not know how to store it in memory\&.
205
206 .PP
207 This function lets applications set \fRimport_cb\fP to a callback function that will get the XML-stored userdata and store it in the object as expected by the application\&.
208
209 .PP
210 \fRimport_cb\fP is called during \fBhwloc_topology_load()\fP as many times as \fBhwloc_export_obj_userdata()\fP was called during export\&. The topology is not entirely setup yet\&. Object attributes are ready to consult, but links between objects are not\&.
211
212 .PP
213 \fRimport_cb\fP may be \fRNULL\fP if userdata should be ignored during import\&.
214
215 .PP
216 \fBNote\fP
217 .RS 4
218 \fRbuffer\fP contains \fRlength\fP characters followed by a null byte ('\\0')\&.
219
220 .PP
221 This function should be called before \fBhwloc_topology_load()\fP\&.
222
223 .PP
224 The topology-specific userdata pointer is ignored when importing from XML\&.
225 .RE
226 .PP
227
228 .SH "Author"
229 .PP
230 Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.