| 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\&. |