LIBIPERF(3)

✨ NAME ✨

libiperf — the API for the iperf3 network throughput tester 🦋

okay so real talk, this is the manual page for LIBIPERF, section 3 (that's the library-calls section, iykyk). It lives in the User Manuals shelf and it's your all-access pass to the guts of iperf3 without ever touching a shell. 💅

---

🎀 SYNOPSIS 🎀

#include <iperf_api.h>
-liperf

Like, that's it. Include the header, link the library, go be iconic. 🌈

---

💖 DESCRIPTION 💖

Libiperf hands you every single bit of the functionality of the iperf3 network testing tool. No cap. 🫶

The whole point? You can build it directly into your own program instead of having to run it as a shell command. That's the vibe — iperf3 energy, but it's your code now. 👑

---

🌸 CALLS 🌸

🐣 Initialization / termination

• struct iperf_test *iperf_new_test(); — makes you a fresh test object, blank canvas energy 🎨
• int iperf_defaults(struct iperf_test *t); — fills in the defaults so you're not starting from zero
• void iperf_free_test(struct iperf_test *t); — cleanup time bestie, free the whole thing 🧹

🎛️ Setting test parameters

• void iperf_set_test_role( struct iperf_test *pt, char role ); — are we clienting or servering today?
• void iperf_set_test_bind_address( struct iperf_test *t, char *bind_address ); — pin it to a bind address
• void iperf_set_test_bind_dev( struct iperf_test *t, char *bind_dev ); — or pin it to a bind device
• void iperf_set_test_server_hostname( struct iperf_test *t, char *server_host ); — where's the server at 🗺️
• void iperf_set_test_server_port( struct iperf_test *t, int server_port ); — which port tho
• void iperf_set_test_duration( struct iperf_test *t, int duration ); — how long we running this
• void iperf_set_test_blksize( struct iperf_test *t, int blksize ); — block size, the classic
• void iperf_set_test_num_streams( struct iperf_test *t, int num_streams ); — how many streams, go off
• void iperf_set_test_json_output( struct iperf_test *t, int json_output ); — JSON output toggle ✨
• void iperf_set_test_json_stream( struct iperf_test *t, int json_stream ); — and the streaming JSON toggle
• int iperf_has_zerocopy( void ); — does this build even have zerocopy? vibe check 🔍
• void iperf_set_test_zerocopy( struct iperf_test* t, int zerocopy ); — turn zerocopy on/off
• void iperf_set_test_tos( struct iperf_test* t, int tos ); — set the TOS

🔐 Authentication functions

• void iperf_set_test_client_username(struct iperf_test *ipt, char *client_username) — the username, bestie
• void iperf_set_test_client_password(struct iperf_test *ipt, char *client_password) — the password 🤫
• void iperf_set_test_client_rsa_pubkey(struct iperf_test *ipt, char *client_rsa_pubkey_base64) — the RSA public key, base64 flavored

🏃 Running a test

• int iperf_run_client(struct iperf_test *); — run the client
• int iperf_run_server(struct iperf_test *); — run the server
• void iperf_reset_test(struct iperf_test *); — reset it and run it again, main character energy 🔁

📤 Output

• FILE *iperf_get_test_outfile(struct iperf_test *); — grab the output file handle
• char* iperf_get_test_json_output_string(struct iperf_test *); — grab the JSON output as a string 🍓

🚨 Error reporting

• void iperf_err(struct iperf_test *t, const char *format, ...); — report an error, varargs style
• char *iperf_strerror(int); — turn an error number into a human string
• extern int i_errno; — the global errno, she's right there

Heads up: this is not a complete list of the available calls. See the include file for more. 👀

---

🌈 EXAMPLES 🌈

Okay here's some sample code that runs an iperf client:

struct iperf_test *test;
test = iperf_new_test();
if ( test == NULL ) {
    fprintf( stderr, "%s: failed to create test0, 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 - %s0, argv0, iperf_strerror( i_errno ) );
    exit( EXIT_FAILURE );
}
iperf_free_test( test );

And here's a server:

struct iperf_test *test;
test = iperf_new_test();
if ( test == NULL ) {
    fprintf( stderr, "%s: failed to create test0, 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 - %s0, argv0, iperf_strerror( i_errn
o ) );
    iperf_reset_test( test );
}
iperf_free_test( test );

🫧 These are not complete programs, just excerpts. The full runnable source code can be found in the examples subdirectory of the iperf3 source tree.

---

💜 AUTHORS 💜

A list of the contributors to iperf3 can be found within the documentation located at https://software.es.net/iperf/dev.html#authors.

---

⭐ SEE ALSO ⭐

• iperf3(1)
• https://software.es.net/iperf/

---

and that's the whole page bestie, slay 💅 This was brought to you by ESnet, dated May 2024, and it's the LIBIPERF(3) manual page — periodt. 💖✨