GCredentials: GIO Reference Manual

## GCredentials GCredentials — An object containing credentials |

## Functions

GCredentials * | g_credentials_new ()
gchar * | g_credentials_to_string ()
gpointer | g_credentials_get_native ()
void | g_credentials_set_native ()
gboolean | g_credentials_is_same_user ()
uid_t | g_credentials_get_unix_user ()
gboolean | g_credentials_set_unix_user ()
pid_t | g_credentials_get_unix_pid ()

## Types and Values

| GCredentials
enum | GCredentialsType

## Object Hierarchy

        GEnum
        ╰── GCredentialsType
        GObject
        ╰── GCredentials

## Includes

    #include <gio/gio.h>

## Description

The GCredentials type is a reference-counted wrapper for native credentials. This information is typically used for identifying, authenticating and authorizing other processes.

Some operating systems supports looking up the credentials of the remote peer of a communication endpoint - see e.g. `g_socket_get_credentials()`.

Some operating systems supports securely sending and receiving credentials over a Unix Domain Socket, see GUnixCredentialsMessage, `g_unix_connection_send_credentials()` and `g_unix_connection_receive_credentials()` for details.

On Linux, the native credential type is a `struct ucred` - see the unix(7) man page for details. This corresponds to `G_CREDENTIALS_TYPE_LINUX_UCRED`.

On Apple operating systems (including iOS, tvOS, and macOS), the native credential type is a `struct xucred`. This corresponds to `G_CREDENTIALS_TYPE_APPLE_XUCRED`.

On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native credential type is a `struct cmsgcred`. This corresponds to `G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED`.

On NetBSD, the native credential type is a `struct unpcbid`. This corresponds to `G_CREDENTIALS_TYPE_NETBSD_UNPCBID`.

On OpenBSD, the native credential type is a `struct sockpeercred`. This corresponds to `G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED`.

On Solaris (including OpenSolaris and its derivatives), the native credential type is a `ucred_t`. This corresponds to `G_CREDENTIALS_TYPE_SOLARIS_UCRED`.

Since GLib 2.72, on Windows, the native credentials may contain the PID of a process. This corresponds to `G_CREDENTIALS_TYPE_WIN32_PID`.

## Functions

### g_credentials_new ()

    GCredentials *
    g_credentials_new (void);

Creates a new GCredentials object with credentials matching the the current process.

#### Returns

A GCredentials. Free with `g_object_unref()`.

[transfer full]

Since: 2.26

### g_credentials_to_string ()

    gchar *
    g_credentials_to_string (GCredentials *credentials);

Creates a human-readable textual representation of `credentials` that can be used in logging and debug messages. The format of the returned string may change in future GLib release.

#### Parameters

credentials | A GCredentials object. |

#### Returns

A string that should be freed with `g_free()`.

[transfer full]

Since: 2.26

### g_credentials_get_native ()

    gpointer
    g_credentials_get_native (GCredentials *credentials,
                              GCredentialsType native_type);

Gets a pointer to native credentials of type `native_type` from `credentials` .

It is a programming error (which will cause a warning to be logged) to use this method if there is no GCredentials support for the OS or if `native_type` isn't supported by the OS.

[skip]

#### Parameters

credentials | A GCredentials. |
native_type | The type of native credentials to get. |

#### Returns

The pointer to native credentials or `NULL` if there is no GCredentials support for the OS or if `native_type` isn't supported by the OS. Do not free the returned data, it is owned by `credentials` .

[transfer none][nullable]

Since: 2.26

### g_credentials_set_native ()

    void
    g_credentials_set_native (GCredentials *credentials,
                              GCredentialsType native_type,
                              gpointer native);

Copies the native credentials of type `native_type` from `native` into `credentials` .

It is a programming error (which will cause a warning to be logged) to use this method if there is no GCredentials support for the OS or if `native_type` isn't supported by the OS.

#### Parameters

credentials | A GCredentials. |
native_type | The type of native credentials to set. |
native | A pointer to native credentials. | [not nullable]

Since: 2.26

### g_credentials_is_same_user ()

    gboolean
    g_credentials_is_same_user (GCredentials *credentials,
                                GCredentials *other_credentials,
                                GError **error);

Checks if `credentials` and `other_credentials` is the same user.

This operation can fail if GCredentials is not supported on the the OS.

#### Parameters

credentials | A GCredentials. |
other_credentials | A GCredentials. |
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if `credentials` and `other_credentials` has the same user, `FALSE` otherwise or if `error` is set.

Since: 2.26

### g_credentials_get_unix_user ()

    uid_t
    g_credentials_get_unix_user (GCredentials *credentials,
                                 GError **error);

Tries to get the UNIX user identifier from `credentials` . This method is only available on UNIX platforms.

This operation can fail if GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX user.

#### Parameters

credentials | A GCredentials |
error | Return location for error or `NULL`. |

#### Returns

The UNIX user identifier or `-1` if `error` is set.

Since: 2.26

### g_credentials_set_unix_user ()

    gboolean
    g_credentials_set_unix_user (GCredentials *credentials,
                                 uid_t uid,
                                 GError **error);

Tries to set the UNIX user identifier on `credentials` . This method is only available on UNIX platforms.

This operation can fail if GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX user. It can also fail if the OS does not allow the use of "spoofed" credentials.

#### Parameters

credentials | A GCredentials. |
uid | The UNIX user identifier to set. |
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if `uid` was set, `FALSE` if error is set.

Since: 2.26

### g_credentials_get_unix_pid ()

    pid_t
    g_credentials_get_unix_pid (GCredentials *credentials,
                                GError **error);

Tries to get the UNIX process identifier from `credentials` . This method is only available on UNIX platforms.

This operation can fail if GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX process ID.

#### Parameters

credentials | A GCredentials |
error | Return location for error or `NULL`. |

#### Returns

The UNIX process ID, or `-1` if `error` is set.

Since: 2.36

## Types and Values

### GCredentials

    typedef struct _GCredentials GCredentials;

The GCredentials structure contains only private data and should only be accessed using the provided API.

Since: 2.26

### enum GCredentialsType

Enumeration describing different kinds of native credential types.

#### Members

G_CREDENTIALS_TYPE_INVALID | Indicates an invalid native credential type. |
G_CREDENTIALS_TYPE_LINUX_UCRED | The native credentials type is a `struct ucred`. |
G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED | The native credentials type is a `struct cmsgcred`. |
G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED | The native credentials type is a `struct sockpeercred`. Added in 2.30. |
G_CREDENTIALS_TYPE_SOLARIS_UCRED | The native credentials type is a `ucred_t`. Added in 2.40. |
G_CREDENTIALS_TYPE_NETBSD_UNPCBID | The native credentials type is a `struct unpcbid`. Added in 2.42. |
G_CREDENTIALS_TYPE_APPLE_XUCRED | The native credentials type is a `struct xucred`. Added in 2.66. |
G_CREDENTIALS_TYPE_WIN32_PID | The native credentials type is a PID `DWORD`. Added in 2.72. |

Since: 2.26