README.md.in

[![Travis](https://api.travis-ci.org/tmds/Tmds.LibC.svg?branch=master)](https://travis-ci.org/tmds/Tmds.LibC)
[![NuGet](https://img.shields.io/nuget/v/Tmds.LibC.svg)](https://www.nuget.org/packages/Tmds.LibC)
# Tmds.LibC

Raw bindings to Linux platform APIs for .NET Core.

## Raw bindings

The APIs provided by this package stay as close as possible to the native declarations.
Because the native APIs are different per platform (e.g. linux-arm64 vs linux-x64), the package contains separate assemblies for each platform.

.NET Core will use the appropriate assembly based on the [rid](https://docs.microsoft.com/en-us/dotnet/core/rid-catalog).

## Supported platforms

* linux x64 glibc
* linux arm64 glibc
* linux arm32 glibc

## Using this package

Add the package using the `dotnet` cli:
```
$ dotnet add package Tmds.LibC
```

Alternatively, you can use a daily build from the https://www.myget.org/F/tmds/api/v3/index.json NuGet feed.

Program.cs

```cs
using System;
using System.Text;
using Tmds.Linux;
using static Tmds.Linux.LibC;

namespace console
{
    class Program
    {
        unsafe static void Main(string[] args)
        {
            var bytes = Encoding.UTF8.GetBytes("Hello world!");
            fixed (byte* buffer = bytes)
            {
                write(STDOUT_FILENO, buffer, bytes.Length);
            }
        }
    }
}
```

## Functions

The following functions are defined in the static class `Tmds.Linux.LibC`:

##FUNCTIONS##

## Structs

The following structs are defined in the `Tmds.Linux` namespace:

##STRUCTS##

## Examples

This section shows some examples. The examples use a `PlatformException` class which is implemented as follows:

```c#
class PlatformException : Exception
{
    public PlatformException(int errno) :
        base(GetErrorMessage(errno))
    {
        HResult = errno;
    }

    public PlatformException() :
        this(LibC.errno)
    {}

    private unsafe static string GetErrorMessage(int errno)
    {
        int bufferLength = 1024;
        byte* buffer = stackalloc byte[bufferLength];

        int rv = strerror_r(errno, buffer, bufferLength);

        return rv == 0 ? Marshal.PtrToStringAnsi((IntPtr)buffer) : $"errno {errno}";
    }

    public static void Throw() => throw new PlatformException();
}
```

### Example 1: Socket extension method to set raw socket options

```c#
static class SocketExtensions
{
    public static unsafe void SetRawSocketOption(this Socket socket, int level, int optname, int optval)
    {
        SafeHandle handle = socket.SafeHandle;
        bool refAdded = false;
        try
        {
            handle.DangerousAddRef(ref refAdded);
            int rv = setsockopt(handle.DangerousGetHandle().ToInt32(), level, optname, &optval, sizeof(int));
            if (rv != 0)
            {
                PlatformException.Throw();
            }
        }
        finally
        {
            if (refAdded)
                handle.DangerousRelease();
        }
    }
}
```

This extension method can be used with the constants provided by `Tmds.LibC`, for example:
```c#
socket.SetRawSocketOption(SOL_SOCKET, SO_REUSEADDR, 1);
```

### Example 2: Process extension method to request termination

Unix processes can be requested to terminate using the `SIGTERM` signal. The following code adds an extension
method to the `Process` class to send that signal.

```c#
static class ProcessExtensions
{
    public static void Terminate(this Process process)
    {
        if (process.HasExited)
        {
            return;
        }
        int rv = kill(process.Handle.ToInt32(), SIGTERM);
        if (rv == -1 &&
            errno != ESRCH /* process does not exist, assume it exited */)
        {
            PlatformException.Throw();
        }
    }
}
```

### Example 3: Creating a temporary directory that is only accessible by the user

```c#
static class FileUtils
{
    public unsafe static string CreatePrivateTempDirectory()
    {
        string path = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString());

        int byteLength = Encoding.UTF8.GetByteCount(path) + 1;
        Span<byte> bytes = byteLength <= 128 ? stackalloc byte[byteLength] : new byte[byteLength];
        Encoding.UTF8.GetBytes(path, bytes);

        fixed (byte* pathname = bytes)
        {
            int rv = mkdir(pathname, S_IRWXU);
            if (rv == -1)
            {
                PlatformException.Throw();
            }
        }

        return path;
    }
}
```