Welcome to unix-cred’s documentation!
Cross-platform interfaces
For most use cases, these interfaces (in particular get_peer_uid_gid()
) should be enough.
- get_peer_uid_gid(sock)
Returns the
(uid, gid)
of the peer connected to the given stream socket.
- get_peer_pid_uid_gid(sock)
Returns the
(pid, uid, gid)
of the peer connected to the given stream socket.On some platforms, this function is not available. On other platforms, the returned PID may be
None
if the current version of that platform does not support retrieving the PID (for example, FreeBSD prior to version 13 does not, and will always returnNone
).Availability: Linux, OpenBSD, NetBSD, FreeBSD (PID only available on version 13+), macOS, Solaris, Illumos
Platform-specific interfaces
In most cases, you should use the cross-platform interfaces. However, the platform-specific interfaces may be useful (for example, they may provide additional information).
- get_peerpid(sock)
Returns the PID of the process that last accessed the given stream socket.
Availability: macOS
ucred
The ucred
module provides an interface to the ucred
interface on Linux, the sockpeecred
interface on OpenBSD, or the unpcbid
interface on NetBSD.
The reason that the interfaces for all three of these are in one module is that they are all essentially the same interface, with only minor implementation differences (such as the order of the fields in the C struct, or the name of the socket option used to retrieve them).
Note
This module is only here for completeness. In nearly all cases, you should use
get_peer_pid_uid_gid()
(which has slightly better cross-platform support) instead.
xucred
The xucred
module provides an interface to the xucred
interface on FreeBSD, DragonflyBSD, and macOS.
- class xucred.Xucred
Availability: FreeBSD, DragonFlyBSD, macOS
- pid
- Type
int or None
The PID of the connected peer.
This attribute is only set on FreeBSD 13+. On macOS/DragonFlyBSD, and on previous versions of FreeBSD, it is always
None
. Always make sure to check for aNone
value.To get the PID on macOS, use
get_peerpid()
.Availability: FreeBSD 13+
- uid
- Type
int
The effective UID of the connected peer.
- gid
- Type
int
The effective GID of the connected peer.
- groups
- Type
list[int]
The supplementary groups of the connected peer.
Note
On macOS, the value placed in this attribute differs from that of os.getgroups(). Effectively, it always behaves as if the deployment target is less than 10.5.
Note
On FreeBSD, this group list is truncated to the first 16 supplementary groups. (Technically, it’s also truncated on DragonflyBSD and macOS, but they only support 16 groups normally.)
peerucred
The peerucred
module provides an interface to the getpeerucred()
function on Solaris/Illumos.
Warning
This module is experimental and has undergone no testing whatsoever. Use with caution.
- class peerucred.Ucred
Availability: Solaris, Illumos
- pid
- Type
int
The PID of the connected peer.
- ruid
- Type
int
The real UID of the connected peer.
- euid
- Type
int
The effective UID of the connected peer.
- suid
- Type
int
The saved UID of the connected peer.
- rgid
- Type
int
The real GID of the connected peer.
- egid
- Type
int
The effective GID of the connected peer.
- sgid
- Type
int
The saved GID of the connected peer.
- groups
- Type
list[int]
The supplementary groups of the connected peer.