• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * iperf, Copyright (c) 2014-2020, The Regents of the University of
3  * California, through Lawrence Berkeley National Laboratory (subject
4  * to receipt of any required approvals from the U.S. Dept. of
5  * Energy).  All rights reserved.
6  *
7  * If you have questions about your rights to use or distribute this
8  * software, please contact Berkeley Lab's Technology Transfer
9  * Department at TTD@lbl.gov.
10  *
11  * NOTICE.  This software is owned by the U.S. Department of Energy.
12  * As such, the U.S. Government has been granted for itself and others
13  * acting on its behalf a paid-up, nonexclusive, irrevocable,
14  * worldwide license in the Software to reproduce, prepare derivative
15  * works, and perform publicly and display publicly.  Beginning five
16  * (5) years after the date permission to assert copyright is obtained
17  * from the U.S. Department of Energy, and subject to any subsequent
18  * five (5) year renewals, the U.S. Government is granted for itself
19  * and others acting on its behalf a paid-up, nonexclusive,
20  * irrevocable, worldwide license in the Software to reproduce,
21  * prepare derivative works, distribute copies to the public, perform
22  * publicly and display publicly, and to permit others to do so.
23  *
24  * This code is distributed under a BSD style license, see the LICENSE
25  * file for complete information.
26  */
27 #ifndef        __IPERF_API_H
28 #define        __IPERF_API_H
29 
30 #include <sys/socket.h>
31 #include <sys/time.h>
32 #include <setjmp.h>
33 #include <stdio.h>
34 #ifdef HAVE_STDINT_H
35 #include <stdint.h>
36 #endif
37 #ifdef __cplusplus
38 extern "C" { /* open extern "C" */
39 #endif
40 
41 
42 struct iperf_test;
43 struct iperf_stream_result;
44 struct iperf_interval_results;
45 struct iperf_stream;
46 struct iperf_time;
47 
48 #if !defined(__IPERF_H)
49 typedef uint64_t iperf_size_t;
50 #endif // __IPERF_H
51 
52 /* default settings */
53 #define Ptcp SOCK_STREAM
54 #define Pudp SOCK_DGRAM
55 #define Psctp 12
56 #define DEFAULT_UDP_BLKSIZE 1460 /* default is dynamically set, else this */
57 #define DEFAULT_TCP_BLKSIZE (128 * 1024)  /* default read/write block size */
58 #define DEFAULT_SCTP_BLKSIZE (64 * 1024)
59 
60 /* short option equivalents, used to support options that only have long form */
61 #define OPT_SCTP 1
62 #define OPT_LOGFILE 2
63 #define OPT_GET_SERVER_OUTPUT 3
64 #define OPT_UDP_COUNTERS_64BIT 4
65 #define OPT_CLIENT_PORT 5
66 #define OPT_NUMSTREAMS 6
67 #define OPT_FORCEFLUSH 7
68 #define OPT_NO_FQ_SOCKET_PACING 9 /* UNUSED */
69 #define OPT_FQ_RATE 10
70 #define OPT_DSCP 11
71 #define OPT_CLIENT_USERNAME 12
72 #define OPT_CLIENT_RSA_PUBLIC_KEY 13
73 #define OPT_SERVER_RSA_PRIVATE_KEY 14
74 #define OPT_SERVER_AUTHORIZED_USERS 15
75 #define OPT_PACING_TIMER 16
76 #define OPT_CONNECT_TIMEOUT 17
77 #define OPT_REPEATING_PAYLOAD 18
78 #define OPT_EXTRA_DATA 19
79 #define OPT_BIDIRECTIONAL 20
80 #define OPT_SERVER_BITRATE_LIMIT 21
81 #define OPT_TIMESTAMPS 22
82 
83 /* states */
84 #define TEST_START 1
85 #define TEST_RUNNING 2
86 #define RESULT_REQUEST 3 /* not used */
87 #define TEST_END 4
88 #define STREAM_BEGIN 5 /* not used */
89 #define STREAM_RUNNING 6 /* not used */
90 #define STREAM_END 7 /* not used */
91 #define ALL_STREAMS_END 8 /* not used */
92 #define PARAM_EXCHANGE 9
93 #define CREATE_STREAMS 10
94 #define SERVER_TERMINATE 11
95 #define CLIENT_TERMINATE 12
96 #define EXCHANGE_RESULTS 13
97 #define DISPLAY_RESULTS 14
98 #define IPERF_START 15
99 #define IPERF_DONE 16
100 #define ACCESS_DENIED (-1)
101 #define SERVER_ERROR (-2)
102 
103 /* Getter routines for some fields inside iperf_test. */
104 int	iperf_get_verbose( struct iperf_test* ipt );
105 int	iperf_get_control_socket( struct iperf_test* ipt );
106 int	iperf_get_test_omit( struct iperf_test* ipt );
107 int	iperf_get_test_duration( struct iperf_test* ipt );
108 char	iperf_get_test_role( struct iperf_test* ipt );
109 int	iperf_get_test_reverse( struct iperf_test* ipt );
110 int	iperf_get_test_blksize( struct iperf_test* ipt );
111 FILE*	iperf_get_test_outfile( struct iperf_test* ipt );
112 uint64_t iperf_get_test_rate( struct iperf_test* ipt );
113 int iperf_get_test_pacing_timer( struct iperf_test* ipt );
114 uint64_t iperf_get_test_bytes( struct iperf_test* ipt );
115 uint64_t iperf_get_test_blocks( struct iperf_test* ipt );
116 int     iperf_get_test_burst( struct iperf_test* ipt );
117 int	iperf_get_test_socket_bufsize( struct iperf_test* ipt );
118 double	iperf_get_test_reporter_interval( struct iperf_test* ipt );
119 double	iperf_get_test_stats_interval( struct iperf_test* ipt );
120 int	iperf_get_test_num_streams( struct iperf_test* ipt );
121 int	iperf_get_test_repeating_payload( struct iperf_test* ipt );
122 int	iperf_get_test_timestamps( struct iperf_test* ipt );
123 const char* iperf_get_test_timestamp_format( struct iperf_test* ipt );
124 int	iperf_get_test_server_port( struct iperf_test* ipt );
125 char*	iperf_get_test_server_hostname( struct iperf_test* ipt );
126 char*	iperf_get_test_template( struct iperf_test* ipt );
127 int	iperf_get_test_protocol_id( struct iperf_test* ipt );
128 int	iperf_get_test_json_output( struct iperf_test* ipt );
129 char*	iperf_get_test_json_output_string ( struct iperf_test* ipt );
130 int	iperf_get_test_zerocopy( struct iperf_test* ipt );
131 int	iperf_get_test_get_server_output( struct iperf_test* ipt );
132 char*	iperf_get_test_bind_address ( struct iperf_test* ipt );
133 int	iperf_get_test_udp_counters_64bit( struct iperf_test* ipt );
134 int	iperf_get_test_one_off( struct iperf_test* ipt );
135 int iperf_get_test_tos( struct iperf_test* ipt );
136 char*	iperf_get_extra_data( struct iperf_test* ipt );
137 char*	iperf_get_iperf_version(void);
138 int	iperf_get_test_no_delay( struct iperf_test* ipt );
139 int	iperf_get_test_connect_timeout( struct iperf_test* ipt );
140 
141 /* Setter routines for some fields inside iperf_test. */
142 void	iperf_set_verbose( struct iperf_test* ipt, int verbose );
143 void	iperf_set_control_socket( struct iperf_test* ipt, int ctrl_sck );
144 void	iperf_set_test_omit( struct iperf_test* ipt, int omit );
145 void	iperf_set_test_duration( struct iperf_test* ipt, int duration );
146 void	iperf_set_test_reporter_interval( struct iperf_test* ipt, double reporter_interval );
147 void	iperf_set_test_stats_interval( struct iperf_test* ipt, double stats_interval );
148 void	iperf_set_test_state( struct iperf_test* ipt, signed char state );
149 void	iperf_set_test_blksize( struct iperf_test* ipt, int blksize );
150 void	iperf_set_test_logfile( struct iperf_test* ipt, const char *logfile );
151 void	iperf_set_test_rate( struct iperf_test* ipt, uint64_t rate );
152 void    iperf_set_test_pacing_timer( struct iperf_test* ipt, int pacing_timer );
153 void    iperf_set_test_bytes( struct iperf_test* ipt, uint64_t bytes );
154 void    iperf_set_test_blocks( struct iperf_test* ipt, uint64_t blocks );
155 void	iperf_set_test_burst( struct iperf_test* ipt, int burst );
156 void	iperf_set_test_server_port( struct iperf_test* ipt, int server_port );
157 void	iperf_set_test_socket_bufsize( struct iperf_test* ipt, int socket_bufsize );
158 void	iperf_set_test_num_streams( struct iperf_test* ipt, int num_streams );
159 void	iperf_set_test_repeating_payload( struct iperf_test* ipt, int repeating_payload );
160 void	iperf_set_test_timestamps( struct iperf_test* ipt, int timestamps );
161 void	iperf_set_test_timestamp_format( struct iperf_test*, const char *tf );
162 void	iperf_set_test_role( struct iperf_test* ipt, char role );
163 void	iperf_set_test_server_hostname( struct iperf_test* ipt, const char* server_hostname );
164 void    iperf_set_test_template( struct iperf_test *ipt, const char *tmp_template );
165 void	iperf_set_test_reverse( struct iperf_test* ipt, int reverse );
166 void	iperf_set_test_json_output( struct iperf_test* ipt, int json_output );
167 int	iperf_has_zerocopy( void );
168 void	iperf_set_test_zerocopy( struct iperf_test* ipt, int zerocopy );
169 void	iperf_set_test_get_server_output( struct iperf_test* ipt, int get_server_output );
170 void	iperf_set_test_bind_address( struct iperf_test* ipt, const char *bind_address );
171 void	iperf_set_test_udp_counters_64bit( struct iperf_test* ipt, int udp_counters_64bit );
172 void	iperf_set_test_one_off( struct iperf_test* ipt, int one_off );
173 void    iperf_set_test_tos( struct iperf_test* ipt, int tos );
174 void	iperf_set_test_extra_data( struct iperf_test* ipt, const char *dat );
175 void    iperf_set_test_bidirectional( struct iperf_test* ipt, int bidirectional);
176 void    iperf_set_test_no_delay( struct iperf_test* ipt, int no_delay);
177 
178 #if defined(HAVE_SSL)
179 void    iperf_set_test_client_username(struct iperf_test *ipt, const char *client_username);
180 void    iperf_set_test_client_password(struct iperf_test *ipt, const char *client_password);
181 void    iperf_set_test_client_rsa_pubkey(struct iperf_test *ipt, const char *client_rsa_pubkey_base64);
182 void    iperf_set_test_server_authorized_users(struct iperf_test *ipt, const char *server_authorized_users);
183 void    iperf_set_test_server_rsa_privkey(struct iperf_test *ipt, const char *server_rsa_privkey_base64);
184 #endif // HAVE_SSL
185 
186 void	iperf_set_test_connect_timeout(struct iperf_test *ipt, int ct);
187 
188 /**
189  * exchange_parameters - handles the param_Exchange part for client
190  *
191  */
192 int      iperf_exchange_parameters(struct iperf_test * test);
193 
194 /**
195  * add_to_interval_list -- adds new interval to the interval_list
196  *
197  */
198 void      add_to_interval_list(struct iperf_stream_result * rp, struct iperf_interval_results *temp);
199 
200 /**
201  * connect_msg -- displays connection message
202  * denoting senfer/receiver details
203  *
204  */
205 void      connect_msg(struct iperf_stream * sp);
206 
207 /**
208  * iperf_stats_callback -- handles the statistic gathering
209  *
210  */
211 void     iperf_stats_callback(struct iperf_test * test);
212 
213 /**
214  * iperf_reporter_callback -- handles the report printing
215  *
216  */
217 void     iperf_reporter_callback(struct iperf_test * test);
218 
219 /**
220  * iperf_new_test -- return a new iperf_test with default values
221  *
222  * returns NULL on failure
223  *
224  */
225 struct iperf_test *iperf_new_test(void);
226 
227 int      iperf_defaults(struct iperf_test * testp);
228 
229 /**
230  * iperf_free_test -- free resources used by test, calls iperf_free_stream to
231  * free streams
232  *
233  */
234 void      iperf_free_test(struct iperf_test * testp);
235 
236 /**
237  * iperf_new_stream -- return a net iperf_stream with default values
238  *
239  * returns NULL on failure
240  *
241  */
242 struct iperf_stream *iperf_new_stream(struct iperf_test *, int, int);
243 
244 /**
245  * iperf_add_stream -- add a stream to a test
246  *
247  */
248 void      iperf_add_stream(struct iperf_test * test, struct iperf_stream * stream);
249 
250 /**
251  * iperf_init_stream -- init resources associated with test
252  *
253  */
254 int       iperf_init_stream(struct iperf_stream *, struct iperf_test *);
255 
256 /**
257  * iperf_free_stream -- free resources associated with test
258  *
259  */
260 void      iperf_free_stream(struct iperf_stream * sp);
261 
262 int has_tcpinfo(void);
263 int has_tcpinfo_retransmits(void);
264 void save_tcpinfo(struct iperf_stream *sp, struct iperf_interval_results *irp);
265 long get_total_retransmits(struct iperf_interval_results *irp);
266 long get_snd_cwnd(struct iperf_interval_results *irp);
267 long get_rtt(struct iperf_interval_results *irp);
268 long get_rttvar(struct iperf_interval_results *irp);
269 long get_pmtu(struct iperf_interval_results *irp);
270 void print_tcpinfo(struct iperf_test *test);
271 void build_tcpinfo_message(struct iperf_interval_results *r, char *message);
272 
273 int iperf_set_send_state(struct iperf_test *test, signed char state);
274 void iperf_check_throttle(struct iperf_stream *sp, struct iperf_time *nowP);
275 int iperf_send(struct iperf_test *, fd_set *) /* __attribute__((hot)) */;
276 int iperf_recv(struct iperf_test *, fd_set *);
277 void iperf_catch_sigend(void (*handler)(int));
278 void iperf_got_sigend(struct iperf_test *test) __attribute__ ((noreturn));
279 void usage(void);
280 void usage_long(FILE * f);
281 void warning(const char *);
282 int iperf_exchange_results(struct iperf_test *);
283 int iperf_init_test(struct iperf_test *);
284 int iperf_create_send_timers(struct iperf_test *);
285 int iperf_parse_arguments(struct iperf_test *, int, char **);
286 int iperf_open_logfile(struct iperf_test *);
287 void iperf_reset_test(struct iperf_test *);
288 void iperf_reset_stats(struct iperf_test * test);
289 
290 struct protocol *get_protocol(struct iperf_test *, int);
291 int set_protocol(struct iperf_test *, int);
292 
293 void iperf_on_new_stream(struct iperf_stream *);
294 void iperf_on_test_start(struct iperf_test *);
295 void iperf_on_connect(struct iperf_test *);
296 void iperf_on_test_finish(struct iperf_test *);
297 
298 extern jmp_buf env;
299 
300 /* Client routines. */
301 int iperf_run_client(struct iperf_test *);
302 int iperf_connect(struct iperf_test *);
303 int iperf_create_streams(struct iperf_test *, int sender);
304 int iperf_handle_message_client(struct iperf_test *);
305 int iperf_client_end(struct iperf_test *);
306 
307 /* Server routines. */
308 int iperf_run_server(struct iperf_test *);
309 int iperf_server_listen(struct iperf_test *);
310 int iperf_accept(struct iperf_test *);
311 int iperf_handle_message_server(struct iperf_test *);
312 int iperf_create_pidfile(struct iperf_test *);
313 int iperf_delete_pidfile(struct iperf_test *);
314 void iperf_check_total_rate(struct iperf_test *, iperf_size_t);
315 
316 /* JSON output routines. */
317 int iperf_json_start(struct iperf_test *);
318 int iperf_json_finish(struct iperf_test *);
319 
320 /* CPU affinity routines */
321 int iperf_setaffinity(struct iperf_test *, int affinity);
322 int iperf_clearaffinity(struct iperf_test *);
323 
324 /* Custom printf routine. */
325 int iperf_printf(struct iperf_test *test, const char *format, ...) __attribute__ ((format(printf,2,3)));
326 int iflush(struct iperf_test *test);
327 
328 /* Error routines. */
329 void iperf_err(struct iperf_test *test, const char *format, ...) __attribute__ ((format(printf,2,3)));
330 void iperf_errexit(struct iperf_test *test, const char *format, ...) __attribute__ ((format(printf,2,3),noreturn));
331 char *iperf_strerror(int);
332 extern int i_errno;
333 enum {
334     IENONE = 0,             // No error
335     /* Parameter errors */
336     IESERVCLIENT = 1,       // Iperf cannot be both server and client
337     IENOROLE = 2,           // Iperf must either be a client (-c) or server (-s)
338     IESERVERONLY = 3,       // This option is server only
339     IECLIENTONLY = 4,       // This option is client only
340     IEDURATION = 5,         // test duration too long. Maximum value = %dMAX_TIME
341     IENUMSTREAMS = 6,       // Number of parallel streams too large. Maximum value = %dMAX_STREAMS
342     IEBLOCKSIZE = 7,        // Block size too large. Maximum value = %dMAX_BLOCKSIZE
343     IEBUFSIZE = 8,          // Socket buffer size too large. Maximum value = %dMAX_TCP_BUFFER
344     IEINTERVAL = 9,         // Invalid report interval (min = %gMIN_INTERVAL, max = %gMAX_INTERVAL seconds)
345     IEMSS = 10,             // MSS too large. Maximum value = %dMAX_MSS
346     IENOSENDFILE = 11,      // This OS does not support sendfile
347     IEOMIT = 12,            // Bogus value for --omit
348     IEUNIMP = 13,           // Not implemented yet
349     IEFILE = 14,            // -F file couldn't be opened
350     IEBURST = 15,           // Invalid burst count. Maximum value = %dMAX_BURST
351     IEENDCONDITIONS = 16,   // Only one test end condition (-t, -n, -k) may be specified
352     IELOGFILE = 17,	    // Can't open log file
353     IENOSCTP = 18,	    // No SCTP support available
354     IEBIND = 19,	    // UNUSED:  Local port specified with no local bind option
355     IEUDPBLOCKSIZE = 20,    // Block size invalid
356     IEBADTOS = 21,	    // Bad TOS value
357     IESETCLIENTAUTH = 22,   // Bad configuration of client authentication
358     IESETSERVERAUTH = 23,   // Bad configuration of server authentication
359     IEBADFORMAT = 24,	    // Bad format argument to -f
360     IEREVERSEBIDIR = 25,    // Iperf cannot be both reverse and bidirectional
361     IEBADPORT = 26,	    // Bad port number
362     IETOTALRATE = 27,       // Total required bandwidth is larger than server's limit
363     IETOTALINTERVAL = 28,   // Invalid time interval for calculating average data rate
364     /* Test errors */
365     IENEWTEST = 100,        // Unable to create a new test (check perror)
366     IEINITTEST = 101,       // Test initialization failed (check perror)
367     IELISTEN = 102,         // Unable to listen for connections (check perror)
368     IECONNECT = 103,        // Unable to connect to server (check herror/perror) [from netdial]
369     IEACCEPT = 104,         // Unable to accept connection from client (check herror/perror)
370     IESENDCOOKIE = 105,     // Unable to send cookie to server (check perror)
371     IERECVCOOKIE = 106,     // Unable to receive cookie from client (check perror)
372     IECTRLWRITE = 107,      // Unable to write to the control socket (check perror)
373     IECTRLREAD = 108,       // Unable to read from the control socket (check perror)
374     IECTRLCLOSE = 109,      // Control socket has closed unexpectedly
375     IEMESSAGE = 110,        // Received an unknown message
376     IESENDMESSAGE = 111,    // Unable to send control message to client/server (check perror)
377     IERECVMESSAGE = 112,    // Unable to receive control message from client/server (check perror)
378     IESENDPARAMS = 113,     // Unable to send parameters to server (check perror)
379     IERECVPARAMS = 114,     // Unable to receive parameters from client (check perror)
380     IEPACKAGERESULTS = 115, // Unable to package results (check perror)
381     IESENDRESULTS = 116,    // Unable to send results to client/server (check perror)
382     IERECVRESULTS = 117,    // Unable to receive results from client/server (check perror)
383     IESELECT = 118,         // Select failed (check perror)
384     IECLIENTTERM = 119,     // The client has terminated
385     IESERVERTERM = 120,     // The server has terminated
386     IEACCESSDENIED = 121,   // The server is busy running a test. Try again later.
387     IESETNODELAY = 122,     // Unable to set TCP/SCTP NODELAY (check perror)
388     IESETMSS = 123,         // Unable to set TCP/SCTP MSS (check perror)
389     IESETBUF = 124,         // Unable to set socket buffer size (check perror)
390     IESETTOS = 125,         // Unable to set IP TOS (check perror)
391     IESETCOS = 126,         // Unable to set IPv6 traffic class (check perror)
392     IESETFLOW = 127,        // Unable to set IPv6 flow label
393     IEREUSEADDR = 128,      // Unable to set reuse address on socket (check perror)
394     IENONBLOCKING = 129,    // Unable to set socket to non-blocking (check perror)
395     IESETWINDOWSIZE = 130,  // Unable to set socket window size (check perror)
396     IEPROTOCOL = 131,       // Protocol does not exist
397     IEAFFINITY = 132,       // Unable to set CPU affinity (check perror)
398     IEDAEMON = 133,	    // Unable to become a daemon process
399     IESETCONGESTION = 134,  // Unable to set TCP_CONGESTION
400     IEPIDFILE = 135,	    // Unable to write PID file
401     IEV6ONLY = 136,  	    // Unable to set/unset IPV6_V6ONLY (check perror)
402     IESETSCTPDISABLEFRAG = 137, // Unable to set SCTP Fragmentation (check perror)
403     IESETSCTPNSTREAM= 138,  //  Unable to set SCTP number of streams (check perror)
404     IESETSCTPBINDX= 139,    // Unable to process sctp_bindx() parameters
405     IESETPACING= 140,       // Unable to set socket pacing rate
406     IESETBUF2= 141,	    // Socket buffer size incorrect (written value != read value)
407     IEAUTHTEST = 142,       // Test authorization failed
408     /* Stream errors */
409     IECREATESTREAM = 200,   // Unable to create a new stream (check herror/perror)
410     IEINITSTREAM = 201,     // Unable to initialize stream (check herror/perror)
411     IESTREAMLISTEN = 202,   // Unable to start stream listener (check perror)
412     IESTREAMCONNECT = 203,  // Unable to connect stream (check herror/perror)
413     IESTREAMACCEPT = 204,   // Unable to accepte stream connection (check perror)
414     IESTREAMWRITE = 205,    // Unable to write to stream socket (check perror)
415     IESTREAMREAD = 206,     // Unable to read from stream (check perror)
416     IESTREAMCLOSE = 207,    // Stream has closed unexpectedly
417     IESTREAMID = 208,       // Stream has invalid ID
418     /* Timer errors */
419     IENEWTIMER = 300,       // Unable to create new timer (check perror)
420     IEUPDATETIMER = 301,    // Unable to update timer (check perror)
421 };
422 
423 
424 #ifdef __cplusplus
425 } /* close extern "C" */
426 #endif
427 
428 
429 #endif /* !__IPERF_API_H */
430