How to call a shared c library function from python

// my_library.c

#include <stdio.h>

// A simple function to add two integers
int add(int a, int b) {
    return a + b;
}

// A function to calculate the factorial of a non-negative integer
long long factorial(int n) {
    if (n < 0) {
        fprintf(stderr, "Factorial is not defined for negative numbers.\n");
        return -1; // Indicate an error
    }
    if (n == 0) {
        return 1;
    }
    long long result = 1;
    for (int i = 1; i <= n; i++) {
        result *= i;
    }
    return result;
}

// A function that modifies a string (in-place)
void greet(char *name, char *greeting) {
    sprintf(greeting, "Hello, %s!", name);
}

Explanation:

1. #include <stdio.h>: This line includes the standard input/output library, which provides functions like fprintf and sprintf used in our example.
2. int add(int a, int b):
   • This is a simple C function that takes two integers (a and b) as input.
   • It returns their sum as an integer.
3. long long factorial(int n):
   • This function calculates the factorial of a non-negative integer n.
   • It includes error handling for negative input, printing an error message to the standard error stream (stderr) and returning -1.
   • It uses a loop to calculate the factorial iteratively.
   • The return type is long long to accommodate potentially large factorial values.
4. void greet(char *name, char *greeting):
   • This function takes two character pointers (name and greeting) as input.
   • It uses sprintf to format a greeting string using the provided name and stores the result in the memory location pointed to by greeting.
   • Important: When calling this function from Python, you’ll need to ensure that the Python string you pass for greeting has sufficient buffer space to hold the formatted string.

How to Compile this into a Shared Library:

You’ll need to compile this C code into a shared library (also known as a dynamic library) that Python can load. The compilation command will vary slightly depending on your operating system and compiler (typically GCC).

On Linux:

gcc -shared -o my_library.so my_library.c

• gcc: The GNU C Compiler.
• -shared: This flag tells the compiler to create a shared library.
• -o my_library.so: This specifies the output file name as my_library.so (the .so extension is common for shared libraries on Linux).
• my_library.c: This is the source C file.

On macOS:

gcc -shared -o my_library.dylib my_library.c

• The command is similar to Linux, but the output file extension is typically .dylib on macOS.

On Windows (using MinGW or a similar GCC environment):

gcc -shared -o my_library.dll my_library.c -Wl,--export-all-symbols

• -o my_library.dll: The output file extension is .dll on Windows.
• -Wl,--export-all-symbols: This flag ensures that the functions in the library are exported and can be accessed by Python.

How to Use this Library in Python:

You can use the ctypes module in Python to load and interact with your shared library.

import ctypes
import os

# Load the shared library
# Adjust the path based on where you saved the compiled library
library_path = os.path.abspath("./my_library.so")  # For Linux/macOS
# library_path = os.path.abspath("./my_library.dll") # For Windows
my_lib = ctypes.CDLL(library_path)

# 1. Call the 'add' function
# Specify the argument and return types
my_lib.add.argtypes = [ctypes.c_int, ctypes.c_int]
my_lib.add.restype = ctypes.c_int
result_add = my_lib.add(5, 3)
print(f"Result of addition: {result_add}")

# 2. Call the 'factorial' function
my_lib.factorial.argtypes = [ctypes.c_int]
my_lib.factorial.restype = ctypes.c_longlong
result_factorial = my_lib.factorial(5)
print(f"Factorial of 5: {result_factorial}")

# Call factorial with a negative number to see the error handling
result_factorial_negative = my_lib.factorial(-2)
print(f"Factorial of -2: {result_factorial_negative}")

# 3. Call the 'greet' function
my_lib.greet.argtypes = [ctypes.c_char_p, ctypes.c_char_p]
my_lib.greet.restype = None  # void function

name = "Python User".encode('utf-8')
greeting_buffer = ctypes.create_string_buffer(50)  # Allocate buffer space

my_lib.greet(name, greeting_buffer)
print(f"Greeting: {greeting_buffer.value.decode('utf-8')}")

Explanation of the Python Code:

1. import ctypes: Imports the ctypes module, which provides tools for interacting with C libraries.
2. import os: Imports the os module for path manipulation.
3. library_path = os.path.abspath("./my_library.so") (or .dll): Constructs the absolute path to your compiled shared library. Make sure to adjust the filename and path if your library is in a different location.
4. my_lib = ctypes.CDLL(library_path): Loads the shared library into the my_lib object. CDLL is used for standard C calling conventions.
5. my_lib.add.argtypes = [ctypes.c_int, ctypes.c_int]: Specifies the argument types for the add function in the C library. ctypes.c_int corresponds to C’s int.
6. my_lib.add.restype = ctypes.c_int: Specifies the return type for the add function.
7. result_add = my_lib.add(5, 3): Calls the add function from the C library with the arguments 5 and 3. The result is stored in result_add.
8. Similar steps are followed for the factorial function, using ctypes.c_longlong for the long long return type.
9. For the greet function:
   • my_lib.greet.argtypes = [ctypes.c_char_p, ctypes.c_char_p] indicates that the function expects two C-style strings (character pointers).
   • my_lib.greet.restype = None indicates that the function has a void return type (it doesn’t return a value).
   • name = "Python User".encode('utf-8') encodes the Python string into a bytes object, which ctypes can pass as a C-style string.
   • greeting_buffer = ctypes.create_string_buffer(50) creates a mutable buffer of 50 bytes to hold the greeting string that the C function will write into.
   • my_lib.greet(name, greeting_buffer) calls the C greet function, passing the encoded name and the buffer.
   • greeting_buffer.value.decode('utf-8') retrieves the null-terminated string from the buffer and decodes it back into a Python string.

Key Considerations:

• Data Type Mapping: You need to carefully map C data types to their corresponding ctypes equivalents (e.g., int to ctypes.c_int, double to ctypes.c_double, char * to ctypes.c_char_p, etc.).
• Error Handling: Implement robust error handling in your C code and consider how you want to expose errors to Python (e.g., by returning error codes).
• Memory Management: Be mindful of memory allocated in C. If your C functions allocate memory that needs to be freed, you’ll need to provide a way to do this from Python (e.g., by creating another C function to free the memory).
• String Handling: When working with strings, ensure proper encoding and buffer management to avoid buffer overflows.
• Complex Data Structures: For more complex data structures (like structs or arrays), you’ll need to define corresponding ctypes.Structure or ctypes.Array types in your Python code.

This example provides a basic foundation for creating and using C function libraries in Python. For more advanced scenarios, you might explore tools like Cython or SWIG, which can simplify the process of creating Python bindings for C and C++ code.