1 [](http://travis-ci.org/Seagate/kinetic-c)
2 Kinetic C Client Library
3 ========================
4 The [Github kinetic-c Git repository](https://github.com/Seagate/kinetic-c) contains code for producing Kinetic C clients for interacting with Kinetic storage object-based storage. The library uses the cross-platform Seagate Kinetic protocol for standardizing interaces between the Java simulator and Kinetic Device storage clusters.
6 Reference code is included as part of the [kinetic-c client library test utility (`kinetic-c-util`)](src/utility), which builds and links against the installed `kinetic-c-client` static library. [Additional examples](src/examples) are included for the various types of I/O operations (e.g. blocking/non-blocking, single/multi-threaded). See below for more details.
8 The [project Makefile](Makefile) can be used as a reference for developing a Makefile-based project for building for a custom Kinetic Storage C client driver and/or a high-level C library.
10 Kinetic Protocol Support
11 ------------------------
14 * [Kinetic Protocol v3.0.5](https://github.com/Seagate/kinetic-protocol/tree/3.0.5)
15 * [ProtoBuf-C v1.1.0](https://github.com/protobuf-c/protobuf-c)
16 * [Google ProtoBuf v2.6.0](https://developers.google.com/protocol-buffers/docs/downloads)
21 * [Open SSL](https://www.openssl.org/) for security and encryption
22 * Installation (if you don't already have OpenSSL installed)
23 * Linux (using apt-get)
24 * `> sudo apt-get install openssl`
26 * `> sudo yum install openssl`
27 * OSX (using [Homebrew](http://brew.sh/))
28 * `> brew install openssl`
29 * [json-c](https://github.com/json-c/json-c) for JSON-formatted ACL definition files
32 * Linux (using apt-get)
33 * `> sudo apt-get install json-c`
35 * `> sudo yum install json-c`
36 * OSX (using [Homebrew](http://brew.sh/))
37 * `> brew install openssl`
38 * via Git submodule (from bundled source)
40 * `> sudo make install_json`
42 A release of OpenSSL that provides TLS 1.1 or newer is required.
44 If the OpenSSL installation is not found, the `OPENSSL_PATH` environment
45 variable may need to be set to its base path, e.g.
46 `export OPENSSL_PATH=/usr/local/openssl/1.0.1k/`.
53 > git clone --recursive https://github.com/seagate/kinetic-c.git
56 **Update to the latest version (previously cloned)**
59 > make config # ensures all git submodules are up to date
61 **Build and install static library**
66 **Clean and uninstall any old versions**
71 **Build example utility and run tests against Kinetic Device simulator**
73 > make start_sims # starts bundled kinetic-java simulators for testing
74 > make all # this is what Travis-CI build does does for regression testing
79 [Kinetic-C API Documentation](http://seagate.github.io/kinetic-c/) (generated with Doxygen)
80 * [Kinetic-C API](http://seagate.github.io/kinetic-c/kinetic__client_8h.html)
81 * [Kinetic-C types](http://seagate.github.io/kinetic-c/kinetic__types_8h.html)
82 * [ByteArray API](http://seagate.github.io/kinetic-c/byte__array_8h.html)
83 * The ByteArray and ByteBuffer types are used for exchanging variable length byte-arrays with kinetic-c
84 * e.g. object keys, object value data, etc.
86 **NOTE: Configuration structures `KineticClientConfig` and `KineticSessionConfig` should be initialized per C99 struct initialization or memset to 0 prior to use in order to ensure forward/backward compatibility upon changes to these structure definitions!**
89 ===========================
91 Code examples are included for reference as part of a test utility. The source code for the utility is used to build both a static and dynamically linked verion of the kinetic-c-client library.
93 * `kinetic-c-util` builds/links against Kinetic C static library (.a)
94 * `kinetic-c-util.x.y.z` builds/links against Kinetic C dynamic library (.so)
100 $ ./kinetic-c-util --help
101 Usage: ./bin/kinetic-c-util --<cmd> [options...]
102 ./bin/kinetic-c-util --help
103 ./bin/kinetic-c-util --noop [--host <ip|hostname>] [--port <port>] [--clusterversion <clusterversion>]
104 ./bin/kinetic-c-util --put --key <key> --value <value> [--host <ip|hostname>] [--port <port>] [--clusterversion <clusterversion>]
105 ./bin/kinetic-c-util --get --key <key> [--host <ip|hostname>] [--port <port>] [--clusterversion <clusterversion>]
106 ./bin/kinetic-c-util --getnext --key <key> [--host <ip|hostname>] [--port <port>] [--clusterversion <clusterversion>]
107 ./bin/kinetic-c-util --getprevious --key <key> [--host <ip|hostname>] [--port <port>] [--clusterversion <clusterversion>]
108 ./bin/kinetic-c-util --delete --key <key> [--host <ip|hostname>] [--port <port>] [--clusterversion <clusterversion>]
109 ./bin/kinetic-c-util --getlog --logtype <utilizations|temperatures|capacities|configuration|statistics|messages|limits> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
110 ./bin/kinetic-c-util --getdevicespecificlog --devicelogname <name|ID> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
111 ./bin/kinetic-c-util --setclusterversion --newclusterversion <newclusterversion> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
112 ./bin/kinetic-c-util --seterasepin --pin <oldpin> --newpin <newerasepin> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
113 ./bin/kinetic-c-util --instanterase --pin <erasepin> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
114 ./bin/kinetic-c-util --secureerase --pin <erasepin> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
115 ./bin/kinetic-c-util --setlockpin --pin <oldpin>> <--newpin <newpin> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
116 ./bin/kinetic-c-util --lockdevice --pin <lockpin> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
117 ./bin/kinetic-c-util --unlockdevice --pin <lockpin> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
118 ./bin/kinetic-c-util --setacl --file <acl_json_file> [--host <ip|hostname>] [--tlsport <tlsport>] [--clusterversion <clusterversion>]
119 ./bin/kinetic-c-util --updatefirmware --file <file> --pin <pin> [--host <ip|hostname>] [--port <port>] [--clusterversion <clusterversion>]
121 Kinetic C Client I/O Examples
122 =============================
124 * [`blocking_put_get`](src/examples/blocking_put_get.c) - Blocking put w/get.
125 * [`blocking_put_delete`](src/examples/blocking_put_delete.c) - Blocking put w/delete.
126 * [`put_nonblocking`](src/examples/put_nonblocking.c) - Single thread, single connection, nonblocking put operation.
127 * [`get_nonblocking`](src/examples/get_nonblocking.c) - Single thread, single connection, nonblocking get operation.
128 * [`get_key_range`](src/examples/get_key_range.c) - Query a range of keys from a device.
129 * [`write_file_blocking`](src/examples/write_file_blocking.c) - Single thread, single connection, blocking operation.
130 * [`write_file_blocking_threads`](src/examples/write_file_blocking_threads.c) - Multiple threads, single connection, blocking operations.
131 * [`write_file_nonblocking`](src/examples/write_file_nonblocking.c) - Single thread, single connection, multiple non-blocking operations
132 * [`write_file_blocking_threads`](src/examples/write_file_blocking_threads.c) - Multiple threads, single connection, multiple non-blocking operations.