0
# Cross-Platform Support
1

2
Platform-specific implementations and attachment providers enabling cross-JVM and cross-OS compatibility. Includes support for different attachment mechanisms, process management, and native integrations for maximum compatibility across Java environments.
3

4
## Capabilities
5

6
### Attachment Provider System
7

8
Pluggable attachment provider architecture supporting multiple JVM attachment mechanisms with automatic fallback strategies.
9

10
```java { .api }
11
/**
12
 * An attachment provider is responsible for making the Java attachment API available.
13
 */
14
public interface AttachmentProvider {
15
    /**
16
     * Attempts the creation of an accessor for a specific JVM's attachment API.
17
     * @return The accessor this attachment provider can supply for the currently running JVM
18
     */
19
    Accessor attempt();
20
    
21
    /**
22
     * The default attachment provider to be used.
23
     */
24
    AttachmentProvider DEFAULT = new Compound(
25
        ForModularizedVm.INSTANCE,
26
        ForJ9Vm.INSTANCE,
27
        ForStandardToolsJarVm.JVM_ROOT,
28
        ForStandardToolsJarVm.JDK_ROOT,
29
        ForStandardToolsJarVm.MACINTOSH,
30
        ForUserDefinedToolsJar.INSTANCE,
31
        ForEmulatedAttachment.INSTANCE
32
    );
33
}
34
```
35

36
### Attachment Provider Implementations
37

38
Individual attachment providers for different JVM types and attachment mechanisms.
39

40
```java { .api }
41
/**
42
 * An attachment provider that locates the attach API directly from the system class loader,
43
 * as possible since introducing the Java module system via the jdk.attach module.
44
 */
45
enum ForModularizedVm implements AttachmentProvider;
46

47
/**
48
 * An attachment provider that locates the attach API directly from the system class loader
49
 * expecting an IBM J9 VM.
50
 */
51
enum ForJ9Vm implements AttachmentProvider;
52

53
/**
54
 * An attachment provider that is dependant on the existence of a tools.jar file on the local file system.
55
 */
56
enum ForStandardToolsJarVm implements AttachmentProvider {
57
    JVM_ROOT("../lib/tools.jar"),
58
    JDK_ROOT("lib/tools.jar"), 
59
    MACINTOSH("../Classes/classes.jar");
60
}
61

62
/**
63
 * An attachment provider that attempts to locate a tools.jar from a custom location set via a system property.
64
 */
65
enum ForUserDefinedToolsJar implements AttachmentProvider;
66

67
/**
68
 * An attachment provider that uses Byte Buddy's attachment API emulation. To use this feature, JNA is required.
69
 */
70
enum ForEmulatedAttachment implements AttachmentProvider;
71

72
/**
73
 * A compound attachment provider that attempts the attachment by delegation to other providers.
74
 */
75
class Compound implements AttachmentProvider;
76
```
77

78
### Process Provider System
79

80
Process identification and management system for resolving JVM process IDs across different Java versions and platforms.
81

82
```java { .api }
83
/**
84
 * A process provider is responsible for providing the process id of the current VM.
85
 */
86
public interface ProcessProvider {
87
    /**
88
     * Resolves a process id for the current JVM.
89
     * @return The resolved process id
90
     */
91
    String resolve();
92
}
93

94
/**
95
 * Supplies the current VM's process id.
96
 */
97
enum ForCurrentVm implements ProcessProvider {
98
    INSTANCE;
99
}
100
```
101

102
### Process Provider Implementations
103

104
Platform and Java version specific process ID resolution mechanisms.
105

106
```java { .api }
107
/**
108
 * A process provider for a legacy VM that reads the process id from its JMX properties.
109
 * This strategy is only used prior to Java 9.
110
 */
111
protected enum ForLegacyVm implements ProcessProvider {
112
    INSTANCE;
113
}
114

115
/**
116
 * A process provider for a Java 9 capable VM with access to the introduced process API.
117
 */
118
protected static class ForJava9CapableVm implements ProcessProvider {
119
    /**
120
     * Attempts to create a dispatcher for a Java 9 VM and falls back to a legacy dispatcher
121
     * if this is not possible.
122
     */
123
    public static ProcessProvider make();
124
}
125
```
126

127
### Attachment Type Evaluation
128

129
System for determining whether external process attachment is required based on JVM configuration and version.
130

131
```java { .api }
132
/**
133
 * An attachment evaluator is responsible for deciding if an agent can be attached from the current process.
134
 */
135
protected interface AttachmentTypeEvaluator {
136
    /**
137
     * Checks if the current VM requires external attachment for the supplied process id.
138
     * @param processId The process id of the process to which to attach
139
     * @return true if the current VM requires external attachment for the supplied process
140
     */
141
    boolean requiresExternalAttachment(String processId);
142
}
143
```
144

145
### Platform-Specific Dispatchers
146

147
Cross-platform system integration for process management, file operations, and inter-process communication.
148

149
```java { .api }
150
/**
151
 * A dispatcher for native operations being used for communication with an OpenJ9 virtual machine.
152
 */
153
public interface Dispatcher {
154
    String getTemporaryFolder(String processId);
155
    int pid();
156
    int userId();
157
    boolean isExistingProcess(int processId);
158
    int getOwnerIdOf(File file);
159
    void setPermissions(File file, int permissions);
160
    void incrementSemaphore(File directory, String name, boolean global, int count);
161
    void decrementSemaphore(File directory, String name, boolean global, int count);
162
    void chownFileToUser(File file, long userId);
163
}
164

165
/**
166
 * A connector implementation for a POSIX environment using JNA.
167
 */
168
class ForJnaPosixEnvironment implements Dispatcher;
169

170
/**
171
 * A connector implementation for a Windows environment using JNA.
172
 */
173
class ForJnaWindowsEnvironment implements Dispatcher;
174
```
175

176
## Usage Examples
177

178
### Custom Attachment Provider Strategy
179

180
```java
181
import net.bytebuddy.agent.ByteBuddyAgent;
182
import net.bytebuddy.agent.ByteBuddyAgent.AttachmentProvider;
183

184
// Create custom attachment strategy prioritizing specific mechanisms
185
AttachmentProvider customProvider = new AttachmentProvider.Compound(
186
    AttachmentProvider.ForModularizedVm.INSTANCE,    // Java 9+ modules first
187
    AttachmentProvider.ForJ9Vm.INSTANCE,             // IBM J9 support
188
    AttachmentProvider.ForEmulatedAttachment.INSTANCE // JNA fallback
189
);
190

191
// Use custom provider for installation
192
Instrumentation instrumentation = ByteBuddyAgent.install(customProvider);
193

194
// Use custom provider for attachment
195
File agentJar = new File("my-agent.jar");
196
ByteBuddyAgent.attach(agentJar, "1234", customProvider);
197
```
198

199
### Tools.jar Based Attachment
200

201
```java
202
import net.bytebuddy.agent.ByteBuddyAgent.AttachmentProvider;
203

204
// Try different tools.jar locations
205
AttachmentProvider toolsJarProvider = new AttachmentProvider.Compound(
206
    AttachmentProvider.ForStandardToolsJarVm.JDK_ROOT,    // Standard JDK location
207
    AttachmentProvider.ForStandardToolsJarVm.JVM_ROOT,    // JRE location
208
    AttachmentProvider.ForStandardToolsJarVm.MACINTOSH    // macOS location
209
);
210

211
// Set custom tools.jar location
212
System.setProperty("net.bytebuddy.agent.toolsjar", "/custom/path/tools.jar");
213
AttachmentProvider customToolsJar = AttachmentProvider.ForUserDefinedToolsJar.INSTANCE;
214

215
// Use tools.jar provider
216
Instrumentation instrumentation = ByteBuddyAgent.install(toolsJarProvider);
217
```
218

219
### JNA-Based Attachment
220

221
```java
222
import net.bytebuddy.agent.ByteBuddyAgent.AttachmentProvider;
223

224
// Force JNA-based attachment (requires JNA on classpath)
225
AttachmentProvider jnaProvider = AttachmentProvider.ForEmulatedAttachment.INSTANCE;
226

227
try {
228
    Instrumentation instrumentation = ByteBuddyAgent.install(jnaProvider);
229
    System.out.println("JNA attachment successful");
230
} catch (IllegalStateException e) {
231
    if (e.getMessage().contains("JNA dependency")) {
232
        System.err.println("JNA library not available");
233
    } else {
234
        System.err.println("JNA attachment failed: " + e.getMessage());
235
    }
236
}
237
```
238

239
### Process Provider Configuration
240

241
```java
242
import net.bytebuddy.agent.ByteBuddyAgent.ProcessProvider;
243

244
// Use current VM process provider
245
ProcessProvider currentVM = ProcessProvider.ForCurrentVm.INSTANCE;
246
String currentPid = currentVM.resolve();
247
System.out.println("Current process ID: " + currentPid);
248

249
// Custom process provider implementation
250
ProcessProvider customProvider = new ProcessProvider() {
251
    @Override
252
    public String resolve() {
253
        // Custom logic for process resolution
254
        return System.getProperty("my.app.pid", "1234");
255
    }
256
};
257

258
// Use custom provider for installation
259
Instrumentation instrumentation = ByteBuddyAgent.install(customProvider);
260
```
261

262
### Platform Detection and Adaptation
263

264
```java
265
import net.bytebuddy.agent.VirtualMachine;
266
import com.sun.jna.Platform;
267

268
if (Platform.isWindows()) {
269
    // Windows-specific attachment using named pipes
270
    VirtualMachine vm = VirtualMachine.ForHotSpot.attach("1234", 
271
        new VirtualMachine.ForHotSpot.Connection.ForJnaWindowsNamedPipe.Factory());
272
    
273
} else if (Platform.isSolaris()) {
274
    // Solaris-specific attachment using doors
275
    VirtualMachine vm = VirtualMachine.ForHotSpot.attach("1234",
276
        new VirtualMachine.ForHotSpot.Connection.ForJnaSolarisDoor.Factory(15, 100, TimeUnit.MILLISECONDS));
277
    
278
} else {
279
    // POSIX-based systems (Linux, macOS) using sockets
280
    VirtualMachine vm = VirtualMachine.ForHotSpot.attach("1234",
281
        VirtualMachine.ForHotSpot.Connection.ForJnaPosixSocket.Factory.withDefaultTemporaryFolder(15, 100, TimeUnit.MILLISECONDS));
282
}
283
```
284

285
### JVM Type Detection
286

287
```java
288
import java.util.Locale;
289

290
// Detect JVM type for appropriate provider selection
291
String vmName = System.getProperty("java.vm.name", "").toUpperCase(Locale.US);
292

293
if (vmName.contains("J9")) {
294
    // Use OpenJ9-specific attachment
295
    VirtualMachine vm = VirtualMachine.ForOpenJ9.attach("1234");
296
} else {
297
    // Use HotSpot-compatible attachment
298
    VirtualMachine vm = VirtualMachine.ForHotSpot.attach("1234");
299
}
300
```
301

302
### Error Handling and Diagnostics
303

304
```java
305
import net.bytebuddy.agent.ByteBuddyAgent;
306
import net.bytebuddy.agent.ByteBuddyAgent.AttachmentProvider;
307

308
// Try multiple providers with detailed error reporting
309
AttachmentProvider[] providers = {
310
    AttachmentProvider.ForModularizedVm.INSTANCE,
311
    AttachmentProvider.ForJ9Vm.INSTANCE,
312
    AttachmentProvider.ForStandardToolsJarVm.JDK_ROOT,
313
    AttachmentProvider.ForEmulatedAttachment.INSTANCE
314
};
315

316
Instrumentation instrumentation = null;
317
for (AttachmentProvider provider : providers) {
318
    try {
319
        instrumentation = ByteBuddyAgent.install(provider);
320
        System.out.println("Success with provider: " + provider.getClass().getSimpleName());
321
        break;
322
    } catch (IllegalStateException e) {
323
        System.out.println("Failed with provider " + provider.getClass().getSimpleName() + ": " + e.getMessage());
324
    }
325
}
326

327
if (instrumentation == null) {
328
    System.err.println("All attachment providers failed");
329
}
330
```
331

332
## Platform-Specific Features
333

334
### Windows Support
335

336
- **Named pipe communication**: Efficient inter-process communication using Windows named pipes
337
- **Native extensions**: Pre-compiled DLLs for enhanced attachment capabilities
338
- **Security descriptors**: Proper Windows security handling for cross-user attachment
339
- **Process management**: Windows-specific process enumeration and control
340

341
### Linux Support  
342

343
- **POSIX socket communication**: Unix domain socket-based VM communication
344
- **Process namespace support**: Container and namespace-aware process handling
345
- **File permission management**: POSIX file permission and ownership control
346
- **Semaphore operations**: System V semaphore-based synchronization
347

348
### macOS Support
349

350
- **Darwin-specific paths**: macOS-specific temporary directory resolution
351
- **Framework integration**: Integration with macOS system frameworks
352
- **Code signing compatibility**: Support for signed JVM processes
353
- **Unified memory management**: macOS-specific memory and process management
354

355
### Solaris Support
356

357
- **Door communication**: Solaris door-based high-performance IPC
358
- **Zone awareness**: Solaris container/zone-aware process operations
359
- **Extended attributes**: Solaris-specific file system features
360
- **Privilege management**: Solaris privilege escalation and management
361

362
## Compatibility Matrix
363

364
| Feature | Windows | Linux | macOS | Solaris | AIX |
365
|---------|---------|-------|-------|---------|-----|
366
| JNA Attachment | ✓ | ✓ | ✓ | ✓ | ✓ |
367
| Tools.jar | ✓ | ✓ | ✓ | ✓ | ✓ |
368
| Module System | ✓ | ✓ | ✓ | ✓ | ✓ |
369
| Native Extensions | ✓ | - | - | - | - |
370
| Socket Emulation | - | ✓ | ✓ | - | ✓ |
371
| Door Communication | - | - | - | ✓ | - |
372
373
## Configuration Properties
374

375
System properties for customizing cross-platform behavior:
376

377
- `net.bytebuddy.agent.toolsjar`: Custom tools.jar location
378
- `net.bytebuddy.agent.latent`: Disable self-resolution for attachment
379
- `net.bytebuddy.agent.attacher.dump`: Enable diagnostic dumping
380
- `net.bytebuddy.library.name`: Custom native library name for Windows
381
- `jdk.attach.allowAttachSelf`: Control self-attachment (Java 9+)
382

383
Example configuration:
384

385
```java
386
// Configure custom tools.jar location
387
System.setProperty("net.bytebuddy.agent.toolsjar", "/opt/jdk/lib/tools.jar");
388

389
// Enable diagnostic output
390
System.setProperty("net.bytebuddy.agent.attacher.dump", "/tmp/attachment.log");
391

392
// Allow self-attachment on Java 9+
393
System.setProperty("jdk.attach.allowAttachSelf", "true");
394
```