This is an automated email from the ASF dual-hosted git repository.
sarvekshayr pushed a commit to branch HDDS-9225-website-v2
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/HDDS-9225-website-v2 by this
push:
new 1b1cdac28 HDDS-14309. [Website v2] [Docs] [User Guide] C/C++ (#216)
1b1cdac28 is described below
commit 1b1cdac2845fd66da4d6d1f66db92b5045a00fd7
Author: Eric C. Ho <[email protected]>
AuthorDate: Tue Jan 6 21:50:24 2026 +0800
HDDS-14309. [Website v2] [Docs] [User Guide] C/C++ (#216)
---
.markdownlint.yaml | 1 +
cspell.yaml | 2 +
.../01-client-interfaces/08-native-cpp.md | 121 +++++++++++++++++++++
3 files changed, 124 insertions(+)
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
index a7f1ef399..e56120d3a 100644
--- a/.markdownlint.yaml
+++ b/.markdownlint.yaml
@@ -75,6 +75,7 @@ proper-names:
# Acronyms:
- FSO
- OBS
+ - OFS
- ofs
- HttpFS
- CLI
diff --git a/cspell.yaml b/cspell.yaml
index 67c8a335a..fdac35f33 100644
--- a/cspell.yaml
+++ b/cspell.yaml
@@ -90,6 +90,7 @@ words:
- quasi-close
- quasi-closed
- HCFS
+- libo3fs
# Other systems' words
- KDC
- classpath
@@ -147,6 +148,7 @@ words:
- rebalancing
- JDK
- CMDB
+- JNI
# Company names for "Who Uses Ozone" page
- Shopee
- Qihoo360
diff --git a/docs/04-user-guide/01-client-interfaces/08-native-cpp.md
b/docs/04-user-guide/01-client-interfaces/08-native-cpp.md
new file mode 100644
index 000000000..c8ab42ed8
--- /dev/null
+++ b/docs/04-user-guide/01-client-interfaces/08-native-cpp.md
@@ -0,0 +1,121 @@
+---
+sidebar_label: Native C/C++ Client Access to Ozone
+---
+
+# Native C/C++ Client Access to Ozone
+
+## Components Summary
+
+- **libhdfs**: The standard Hadoop C API. It is a JNI bridge between C/C++ and
Java FileSystem implementations.
+- **libo3fs**: Lightweight wrapper exposing a simplified API for Ozone
clients. It is built on top of `libhdfs`.
+- **OFS (Ozone FileSystem)**: Java-based filesystem client used internally by
`libhdfs` to interact with Ozone.
+
+## Overview
+
+Native C/C++ applications can access Ozone volumes and buckets using Hadoop
HDFS's `libhdfs` JNI library.
+As an example, Apache Impala uses this library to access Ozone.
+
+To demonstrate, we built a simple wrapper
[`libo3fs`](https://github.com/apache/hadoop-ozone/tree/master/hadoop-ozone/native-client/libo3fs)
around `libhdfs`.
+Applications can choose to use either `libo3fs` or directly use the low level
`libhdfs` library for basic file operations.
+
+## Architecture and Design Notes
+
+The native client leverages the Hadoop `libhdfs` C API for low-level JNI
bindings, and implements additional wrappers in `libo3fs` to support Ozone
semantics. Internally:
+
+- `libo3fs` wraps Ozone FileSystem APIs for basic file operations (read/write).
+- `libhdfs` implements JNI interface.
+- JNI calls link back to a JVM-based Ozone client to execute operations.
+
+## Building the C/C++ Client Library
+
+### Prerequisites
+
+- Apache Ozone built from source (`ozone-dist/`)
+- Hadoop with compiled `libhdfs.so`
+- Java 8 or later
+- Linux (kernel > 2.6.9)
+
+The following steps assume you have Ozone built from source code, the Hadoop
binary distribution downloaded and extracted,
+and the environment variables `OZONE_HOME` and `HADOOP_HOME` set to their
respective directories.
+
+### 0. Download Hadoop binary distribution (optional)
+
+```bash
+wget
https://archive.apache.org/dist/hadoop/common/hadoop-3.4.0/hadoop-3.4.0.tar.gz
+tar -xzf hadoop-3.4.0.tar.gz
+```
+
+### 1. Compile the Core Library & Shared Library
+
+```bash
+export JAVA_HOME=/path/to/java
+export HADOOP_HOME=/path/to/hadoop
+export OZONE_HOME=/path/to/ozone
+
+cd $OZONE_HOME/hadoop-ozone/native-client/libo3fs
+gcc -fPIC -pthread \
+ -I$HADOOP_HOME/include \
+ -g -c o3fs.c
+
+gcc -shared -o libo3fs.so o3fs.o \
+ $HADOOP_HOME/lib/native/libhdfs.so
+```
+
+### 2. Compile Sample Applications
+
+```bash
+cd $OZONE_HOME/hadoop-ozone/native-client/libo3fs-examples
+gcc -fPIC -pthread -I$OZONE_HOME/hadoop-ozone/native-client/libo3fs \
+ -I$HADOOP_HOME/include -g -c libo3fs_read.c
+gcc -fPIC -pthread -I$OZONE_HOME/hadoop-ozone/native-client/libo3fs \
+ -I$HADOOP_HOME/include -g -c libo3fs_write.c
+```
+
+### 3. Link Executables
+
+```bash
+# o3fs_read
+gcc -o o3fs_read libo3fs_read.o -L$HADOOP_HOME/lib/native -lhdfs \
+ -L$JAVA_HOME/lib/server -ljvm \
+ -L$OZONE_HOME/hadoop-ozone/native-client/libo3fs -lo3fs -pthread
+
+# o3fs_write
+gcc -o o3fs_write libo3fs_write.o -L$HADOOP_HOME/lib/native -lhdfs \
+ -L$JAVA_HOME/lib/server -ljvm \
+ -L$OZONE_HOME/hadoop-ozone/native-client/libo3fs -lo3fs -pthread
+```
+
+### 4. Environment Variables
+
+```bash
+export CLASSPATH=$($OZONE_HOME/bin/ozone classpath ozone-tools)
+export LD_LIBRARY_PATH=\
+$HADOOP_HOME/lib/native:\
+$JAVA_HOME/lib/server:\
+$OZONE_HOME/hadoop-ozone/native-client/libo3fs
+```
+
+### 5. Run Sample Applications
+
+```shell
+ozone sh volume create my-volume
+ozone sh bucket create /my-volume/my-bucket
+```
+
+```shell
+// o3fs_write writes a 100-byte file named 'file1' using a 100-byte buffer to
the 'my-bucket' bucket in the 'my-volume' volume,
+// connecting to an Ozone Manager (om) on port 9862.
+./o3fs_write file1 100 100 om 9862 my-bucket my-volume
+```
+
+## Limitations
+
+- Only basic file I/O operations are supported (no directory listing, ACLs,
etc.); use `libhdfs` directly for advanced features.
+- JNI dependency requires compatible JVM and shared libraries
+- Testing has been limited to Linux; No Windows nor Mac supported
+
+## References
+
+- [Ozone FileSystem Java
Interface](https://ozone.apache.org/docs/edge/interface/ofs.html)
+- [Hadoop libhdfs
Docs](https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-hdfs/LibHdfs.html)
+- [JNI and Native Libraries in
Hadoop](https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-common/NativeLibraries.html)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
