1 /*
2 * junixsocket
3 *
4 * Copyright 2009-2024 Christian Kohlschütter
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18 package org.newsclub.net.unix;
19
20 import java.lang.ProcessBuilder.Redirect;
21
22 /**
23 * Describes junixsocket capabilities the current environment (system platform, native library,
24 * etc.) may or may not support.
25 *
26 * You can check whether your environment supports a given capability by calling
27 * {@link AFSocket#supports(AFSocketCapability)}.
28 *
29 * You can also manually disable a given capability by specifying a System property of the form
30 * <code>org.newsclub.net.unix.library.disable.<em>CAPABILITY_SOMETHING_SOMETHING</em>=true</code>
31 * when invoking the JVM (make sure this property is set before junixsocket is accessed).
32 *
33 * A simple way to check which capabilities are supported in an environment is to run the
34 * `junixsocket-selftest` jar.
35 */
36 public enum AFSocketCapability {
37 // see org_newsclub_net_unix_NativeUnixSocket.c in junixsocket-native
38
39 /** Socket supports retrieving peer credentials. */
40 CAPABILITY_PEER_CREDENTIALS(0),
41
42 /** Socket supports sending and receiving ancillary messages. */
43 CAPABILITY_ANCILLARY_MESSAGES(1),
44
45 /** Socket supports passing file descriptors via ancillary messages. */
46 CAPABILITY_FILE_DESCRIPTORS(2),
47
48 /** Socket addressing supports the abstract namespace (Linux). */
49 CAPABILITY_ABSTRACT_NAMESPACE(3),
50
51 /** Support for AF_UNIX datagrams. */
52 CAPABILITY_UNIX_DATAGRAMS(4),
53
54 /**
55 * A pair of interconnected sockets can be created natively as AF_UNIX sockets.
56 *
57 * This currently not possible on Windows, but instead emulated via anonymous AF_INET ports when
58 * you use {@link AFSocketPair}. Other systems may provide partial implementations of pipe-based
59 * (i.e., non-socket) pairs.
60 *
61 * This capability is specific to AF_UNIX sockets. Other sockets, such as AF_VSOCK, may not
62 * implement socketpair natively even if this capability is set, but would work-around that
63 * limitation in a similar fashion but maybe without resorting to AF_INET.
64 */
65 CAPABILITY_NATIVE_SOCKETPAIR(5),
66
67 /**
68 * A file descriptor can be converted to {@link Redirect}.
69 *
70 * This feature currently uses Java SDK internals that may change/disappear.
71 */
72 CAPABILITY_FD_AS_REDIRECT(6),
73
74 /**
75 * Support for AF_TIPC.
76 *
77 * Availability of this feature is checked upon launch and therefore loading the "tipc" kernel
78 * module at a later point may not be properly reflected.
79 */
80 CAPABILITY_TIPC(7),
81
82 /**
83 * Support for AF_UNIX.
84 *
85 * Availability of this feature is checked upon launch and therefore, on systems adding support at
86 * a later point, may not be properly reflected when checking at a later point.
87 *
88 * NOTE: While this capability is typically supported on most systems that can actually load a
89 * junixsocket JNI library, it is unavailable for older Windows versions (such as 8.1, 10 before
90 * AFUNIX.SYS was included, etc.) and on systems where support for UNIX domain sockets is actively
91 * disabled. Therefore, it is still recommended to check for this capability.
92 */
93 CAPABILITY_UNIX_DOMAIN(8),
94
95 /**
96 * Support for AF_VSOCK.
97 *
98 * Availability of this feature is checked upon launch and therefore enabling vsock at a later
99 * point may not be properly reflected.
100 *
101 * @see #CAPABILITY_VSOCK_DGRAM
102 */
103 CAPABILITY_VSOCK(9),
104
105 /**
106 * Support for AF_VSOCK datagrams (not all platforms/kernel versions or configurations support
107 * this).
108 *
109 * Availability of this feature is checked upon launch and therefore enabling vsock at a later
110 * point may not be properly reflected.
111 */
112 CAPABILITY_VSOCK_DGRAM(10),
113
114 /**
115 * Support for zero-length send(2).
116 *
117 * This can be used to perform a connection check, but not all operating systems support this or
118 * behave correctly (particularly, IBM AIX, IBM i, and IBM z/OS) at the moment.
119 *
120 * If not supported, junixsocket will simply ignore writes of zero-length, and connection checking
121 * with {@link AFSocket#checkConnectionClosed()} may return {@code false} regardless of the actual
122 * condition.
123 */
124 CAPABILITY_ZERO_LENGTH_SEND(11),
125
126 /**
127 * Support for "unsafe" operations.
128 *
129 * Trading-in safety for speed or simplicity may be justified sometimes.
130 *
131 * @see Unsafe
132 * @see AFSocket#ensureUnsafeSupported()
133 */
134 CAPABILITY_UNSAFE(12),
135
136 /**
137 * Support for port numbers larger than 65535 (0xffff).
138 *
139 * Not all systems allow setting port numbers beyond the default TCP range (we use JNI tricks for
140 * that). This capability is required for RMI support.
141 */
142 CAPABILITY_LARGE_PORTS(13),
143
144 /**
145 * Support for certain Darwin (macOS Kernel)-specific features, such as the AF_SYSTEM domain.
146 */
147 CAPABILITY_DARWIN(14),
148
149 ; // end of list
150
151 private final int bitmask;
152
153 AFSocketCapability(int bit) {
154 this.bitmask = 1 << bit;
155 }
156
157 int getBitmask() {
158 return bitmask;
159 }
160 }