2939863b1a
Squashed commit of the following:
commit 23ef0d047fb5396df671be9245f7872153fc299c
Author: Bruce A. Mah <bmah@es.net>
Date: Mon Apr 7 13:35:29 2014 -0700
Add a few API calls to the client-side example program so we can
exercise recently-added JSON-related functionality.
commit 5f8301e8d0380133d533da9b2e39ca4ac522e1c3
Author: Bruce A. Mah <bmah@es.net>
Date: Mon Apr 7 13:16:39 2014 -0700
Revert part of earlier change.
We still want to save the JSON for libiperf consumers that might want it,
but preserve the prior behavior of writing that JSON to stdout. This
maintains (roughly) the behavior of older libiperf, in which libiperf
consumers (such as the iperf3 executable) do not need to explicitly print
the JSON if that's all they're doing with it.
commit 173dcdb05867af00103205bfe39d1b71e18689e9
Author: Bruce A. Mah <bmah@es.net>
Date: Tue Mar 25 13:55:45 2014 -0700
Update manpage for newly-added library calls.
Bump document date while here.
Part of Issue #147.
commit 51a275de9463febc440d41cee9d971fcd381e01c
Author: Bruce A. Mah <bmah@es.net>
Date: Tue Mar 25 13:30:09 2014 -0700
Allow consumers of libiperf3 to get the JSON output for a just-completed test.
This changes the behavior of iperf_json_finish() so that it no longer
outputs JSON output, but saves the rendered output in a NUL-terminated
string buffer. After calling iperf_run_server() or iperf_run_client(),
the client application should check iperf_get_test_json_output() to see
if it returns a non-NULL pointer. If so, there is JSON data available
for it to print or otherwise consume. The buffer is automatically
deallocated when the containing iperf_test structure is deallocated
with iperf_free_test().
Also adds a new API call iperf_get_test_outfile() to find the output
FILE* structure.
Modifies the iperf3 application to use the new API. Users of iperf3
will not notice any functional change.
No effect in "normal" output mode (non-JSON).
111 строки
3.4 KiB
Groff
111 строки
3.4 KiB
Groff
.TH LIBIPERF 3 "March 2014" ESnet "User Manuals"
|
|
.SH NAME
|
|
libiperf \- API for iperf3 network throughput tester
|
|
|
|
.SH SYNOPSIS
|
|
#include <iperf_api.h>
|
|
.br
|
|
-liperf
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
Libiperf gives you access to all the functionality of the iperf3
|
|
network testing tool.
|
|
You can build it directly into your own program, instead of having
|
|
to run it as a shell command.
|
|
|
|
.SH CALLS
|
|
Initialization / termination:
|
|
.nf
|
|
struct iperf_test *iperf_new_test();
|
|
int iperf_defaults(struct iperf_test *t);
|
|
void iperf_free_test(struct iperf_test *t);
|
|
.fi
|
|
Setting test parameters:
|
|
.nf
|
|
void iperf_set_test_role( struct iperf_test *pt, char role );
|
|
void iperf_set_test_server_hostname( struct iperf_test *t, char *server_hos
|
|
void iperf_set_test_server_port( struct iperf_test *t, int server_port );
|
|
void iperf_set_test_duration( struct iperf_test *t, int duration );
|
|
void iperf_set_test_blksize( struct iperf_test *t, int blksize );
|
|
void iperf_set_test_num_streams( struct iperf_test *t, int num_streams );
|
|
void iperf_set_test_json_output( struct iperf_test *t, int json_output );
|
|
int iperf_has_zerocopy( void );
|
|
void iperf_set_test_zerocopy( struct iperf_test* t, int zerocopy );
|
|
.fi
|
|
Running a test:
|
|
.nf
|
|
int iperf_run_client(struct iperf_test *);
|
|
int iperf_run_server(struct iperf_test *);
|
|
void iperf_test_reset(struct iperf_test *);
|
|
.fi
|
|
Output:
|
|
.nf
|
|
FILE *iperf_get_test_outfile(struct iperf_test *);
|
|
char* iperf_get_test_json_output_string(struct iperf_test *);
|
|
.fi
|
|
Error reporting:
|
|
.nf
|
|
void iperf_err(struct iperf_test *t, const char *format, ...);
|
|
char *iperf_strerror(int);
|
|
extern int i_errno;
|
|
.fi
|
|
This is not a complete list of the available calls.
|
|
See the include file for more.
|
|
|
|
.SH EXAMPLES
|
|
Here's some sample code that runs an iperf client:
|
|
.nf
|
|
struct iperf_test *test;
|
|
test = iperf_new_test();
|
|
if ( test == NULL ) {
|
|
fprintf( stderr, "%s: failed to create test\n", argv0 );
|
|
exit( EXIT_FAILURE );
|
|
}
|
|
iperf_defaults( test );
|
|
iperf_set_test_role( test, 'c' );
|
|
iperf_set_test_server_hostname( test, host );
|
|
iperf_set_test_server_port( test, port );
|
|
if ( iperf_run_client( test ) < 0 ) {
|
|
fprintf( stderr, "%s: error - %s\n", argv0, iperf_strerror( i_errno ) );
|
|
exit( EXIT_FAILURE );
|
|
}
|
|
iperf_free_test( test );
|
|
.fi
|
|
And here's a server:
|
|
.nf
|
|
struct iperf_test *test;
|
|
test = iperf_new_test();
|
|
if ( test == NULL ) {
|
|
fprintf( stderr, "%s: failed to create test\n", argv0 );
|
|
exit( EXIT_FAILURE );
|
|
}
|
|
iperf_defaults( test );
|
|
iperf_set_test_role( test, 's' );
|
|
iperf_set_test_server_port( test, port );
|
|
for (;;) {
|
|
if ( iperf_run_server( test ) < 0 )
|
|
fprintf( stderr, "%s: error - %s\n\n", argv0, iperf_strerror( i_errn
|
|
o ) );
|
|
iperf_reset_test( test );
|
|
}
|
|
iperf_free_test( test );
|
|
.fi
|
|
These are not complete programs, just excerpts.
|
|
The full runnable source code can be found in the examples subdirectory
|
|
of the iperf3 source tree.
|
|
|
|
.SH AUTHORS
|
|
Iperf was originally written by Mark Gates and Alex Warshavsky.
|
|
Man page and maintence by Jon Dugan <jdugan at x1024 dot net>.
|
|
Other contributions from Ajay Tirumala, Jim Ferguson,
|
|
Feng Qin,
|
|
Kevin Gibbs,
|
|
John Estabrook <jestabro at ncsa.uiuc.edu>,
|
|
Andrew Gallatin <gallatin at gmail.com>,
|
|
Stephen Hemminger <shemminger at linux-foundation.org>
|
|
|
|
.SH "SEE ALSO"
|
|
iperf3(1),
|
|
https://github.com/esnet/iperf
|