Debian Codegraph @

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

raw
1 .TH "hwlocality_setsource" 3 "Version 2.14.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 hwlocality_setsource \- Changing the Source of Topology Discovery
6 .SH SYNOPSIS
7 .br
8 .PP
9 .SS "Enumerations"
10
11 .in +1c
12 .ti -1c
13 .RI "enum \fBhwloc_topology_components_flag_e\fP { \fBHWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST\fP }"
14 .br
15 .in -1c
16 .SS "Functions"
17
18 .in +1c
19 .ti -1c
20 .RI "int \fBhwloc_topology_set_pid\fP (\fBhwloc_topology_t\fP restrict topology, hwloc_pid_t pid)"
21 .br
22 .ti -1c
23 .RI "int \fBhwloc_topology_set_synthetic\fP (\fBhwloc_topology_t\fP restrict topology, const char *restrict description)"
24 .br
25 .ti -1c
26 .RI "int \fBhwloc_topology_set_xml\fP (\fBhwloc_topology_t\fP restrict topology, const char *restrict xmlpath)"
27 .br
28 .ti -1c
29 .RI "int \fBhwloc_topology_set_xmlbuffer\fP (\fBhwloc_topology_t\fP restrict topology, const char *restrict buffer, int size)"
30 .br
31 .ti -1c
32 .RI "int \fBhwloc_topology_set_components\fP (\fBhwloc_topology_t\fP restrict topology, unsigned long flags, const char *restrict name)"
33 .br
34 .in -1c
35 .SH "Detailed Description"
36 .PP
37 These functions must be called between \fBhwloc_topology_init()\fP and \fBhwloc_topology_load()\fP\&. Otherwise, they will return -1 with errno set to \fREBUSY\fP\&.
38
39 .PP
40 If none of the functions below is called, the default is to detect all the objects of the machine that the caller is allowed to access\&.
41
42 .PP
43 This default behavior may also be modified through environment variables if the application did not modify it already\&. Setting HWLOC_XMLFILE in the environment enforces the discovery from a XML file as if \fBhwloc_topology_set_xml()\fP had been called\&. Setting HWLOC_SYNTHETIC enforces a synthetic topology as if \fBhwloc_topology_set_synthetic()\fP had been called\&.
44
45 .PP
46 Finally, HWLOC_THISSYSTEM enforces the return value of \fBhwloc_topology_is_thissystem()\fP\&.
47 .SH "Enumeration Type Documentation"
48 .PP
49 .SS "enum \fBhwloc_topology_components_flag_e\fP"
50
51 .PP
52 Flags to be passed to \fBhwloc_topology_set_components()\fP\&.
53 .PP
54 \fBEnumerator\fP
55 .in +1c
56 .TP
57 \f(BIHWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST \fP
58 Blacklist the target component from being used\&.
59 .SH "Function Documentation"
60 .PP
61 .SS "int hwloc_topology_set_components (\fBhwloc_topology_t\fP restrict topology, unsigned long flags, const char *restrict name)"
62
63 .PP
64 Prevent a discovery component from being used for a topology\&. \fRname\fP is the name of the discovery component that should not be used when loading topology \fRtopology\fP\&. The name is a string such as "cuda"\&.
65
66 .PP
67 For components with multiple phases, it may also be suffixed with the name of a phase, for instance "linux:io"\&.
68
69 .PP
70 \fRflags\fP should be \fBHWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST\fP\&.
71
72 .PP
73 This may be used to avoid expensive parts of the discovery process\&. For instance, CUDA-specific discovery may be expensive and unneeded while generic I/O discovery could still be useful\&.
74
75 .PP
76 \fBReturns\fP
77 .RS 4
78 0 on success\&.
79
80 .PP
81 -1 on error, for instance if flags are invalid\&.
82 .RE
83 .PP
84
85 .SS "int hwloc_topology_set_pid (\fBhwloc_topology_t\fP restrict topology, hwloc_pid_t pid)"
86
87 .PP
88 Change which process the topology is viewed from\&. On some systems, processes may have different views of the machine, for instance the set of allowed CPUs\&. By default, hwloc exposes the view from the current process\&. Calling \fBhwloc_topology_set_pid()\fP permits to make it expose the topology of the machine from the point of view of another process\&.
89
90 .PP
91 \fBNote\fP
92 .RS 4
93 \fRhwloc_pid_t\fP is \fRpid_t\fP on Unix platforms, and \fRHANDLE\fP on native Windows platforms\&.
94
95 .PP
96 -1 is returned and errno is set to \fRENOSYS\fP on platforms that do not support this feature\&.
97
98 .PP
99 The PID will not actually be used until \fBhwloc_topology_load()\fP\&. If the corresponding process exits in the meantime, hwloc will ignore the PID\&. If another process reuses the PID, the view of that process will be used\&.
100 .RE
101 .PP
102 \fBReturns\fP
103 .RS 4
104 0 on success, -1 on error\&.
105 .RE
106 .PP
107
108 .SS "int hwloc_topology_set_synthetic (\fBhwloc_topology_t\fP restrict topology, const char *restrict description)"
109
110 .PP
111 Enable synthetic topology\&. Gather topology information from the given \fRdescription\fP, a space-separated string of <type:number> describing the object type and arity at each level\&. All types may be omitted (space-separated string of numbers) so that hwloc chooses all types according to usual topologies\&. See also the \fBSynthetic topologies\fP\&.
112
113 .PP
114 Setting the environment variable HWLOC_SYNTHETIC may also result in this behavior\&.
115
116 .PP
117 If \fRdescription\fP was properly parsed and describes a valid topology configuration, this function returns 0\&. Otherwise -1 is returned and errno is set to \fREINVAL\fP\&.
118
119 .PP
120 Note that this function does not actually load topology information; it just tells hwloc where to load it from\&. You'll still need to invoke \fBhwloc_topology_load()\fP to actually load the topology information\&.
121
122 .PP
123 \fBReturns\fP
124 .RS 4
125 0 on success\&.
126
127 .PP
128 -1 with errno set to \fREINVAL\fP if the description was invalid\&.
129 .RE
130 .PP
131 \fBNote\fP
132 .RS 4
133 For convenience, this backend provides empty binding hooks which just return success\&.
134
135 .PP
136 On success, the synthetic component replaces the previously enabled component (if any), but the topology is not actually modified until \fBhwloc_topology_load()\fP\&.
137 .RE
138 .PP
139
140 .SS "int hwloc_topology_set_xml (\fBhwloc_topology_t\fP restrict topology, const char *restrict xmlpath)"
141
142 .PP
143 Enable XML-file based topology\&. Gather topology information from the XML file given at \fRxmlpath\fP\&. Setting the environment variable HWLOC_XMLFILE may also result in this behavior\&. This file may have been generated earlier with \fBhwloc_topology_export_xml()\fP in \fBhwloc/export\&.h\fP, or lstopo file\&.xml\&.
144
145 .PP
146 Note that this function does not actually load topology information; it just tells hwloc where to load it from\&. You'll still need to invoke \fBhwloc_topology_load()\fP to actually load the topology information\&.
147
148 .PP
149 \fBReturns\fP
150 .RS 4
151 0 on success\&.
152
153 .PP
154 -1 with errno set to \fREINVAL\fP on failure to read the XML file\&.
155 .RE
156 .PP
157 \fBNote\fP
158 .RS 4
159 See also \fBhwloc_topology_set_userdata_import_callback()\fP for importing application-specific object userdata\&.
160
161 .PP
162 For convenience, this backend provides empty binding hooks which just return success\&. To have hwloc still actually call OS-specific hooks, the \fBHWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM\fP has to be set to assert that the loaded file is really the underlying system\&.
163
164 .PP
165 On success, the XML component replaces the previously enabled component (if any), but the topology is not actually modified until \fBhwloc_topology_load()\fP\&.
166
167 .PP
168 If an invalid XML input file is given, the error may be reported either here or later by \fBhwloc_topology_load()\fP depending on the XML library used by hwloc\&.
169 .RE
170 .PP
171
172 .SS "int hwloc_topology_set_xmlbuffer (\fBhwloc_topology_t\fP restrict topology, const char *restrict buffer, int size)"
173
174 .PP
175 Enable XML based topology using a memory buffer (instead of a file, as with \fBhwloc_topology_set_xml()\fP)\&. Gather topology information from the XML memory buffer given at \fRbuffer\fP and of length \fRsize\fP (including an ending \fR\\0\fP)\&. This buffer may have been filled earlier with \fBhwloc_topology_export_xmlbuffer()\fP in \fBhwloc/export\&.h\fP\&.
176
177 .PP
178 Note that this function does not actually load topology information; it just tells hwloc where to load it from\&. You'll still need to invoke \fBhwloc_topology_load()\fP to actually load the topology information\&.
179
180 .PP
181 \fBReturns\fP
182 .RS 4
183 0 on success\&.
184
185 .PP
186 -1 with errno set to \fREINVAL\fP on failure to read the XML buffer\&.
187 .RE
188 .PP
189 \fBNote\fP
190 .RS 4
191 See also \fBhwloc_topology_set_userdata_import_callback()\fP for importing application-specific object userdata\&.
192
193 .PP
194 For convenience, this backend provides empty binding hooks which just return success\&. To have hwloc still actually call OS-specific hooks, the \fBHWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM\fP has to be set to assert that the loaded file is really the underlying system\&.
195
196 .PP
197 On success, the XML component replaces the previously enabled component (if any), but the topology is not actually modified until \fBhwloc_topology_load()\fP\&.
198
199 .PP
200 If an invalid XML input file is given, the error may be reported either here or later by \fBhwloc_topology_load()\fP depending on the XML library used by hwloc\&.
201 .RE
202 .PP
203
204 .SH "Author"
205 .PP
206 Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.