Documentation
¶
Overview ¶
Package procfs provides a safe API for operating on /proc on Linux.
Index ¶
- Variables
- func UnmaskedProcRoot(how *libpathrs.ProcfsOpenHow) error
- type Handle
- func (proc *Handle) Close() error
- func (proc *Handle) OpenPid(pid int, path string, flags int) (*os.File, error)
- func (proc *Handle) OpenRoot(path string, flags int) (*os.File, error)
- func (proc *Handle) OpenSelf(path string, flags int) (*os.File, error)
- func (proc *Handle) OpenThreadSelf(path string, flags int) (*os.File, ThreadCloser, error)
- func (proc *Handle) Readlink(base ProcBase, path string) (string, error)
- type OpenOption
- type ProcBase
- type ThreadCloser
Constants ¶
This section is empty.
Variables ¶
var ( // ProcRoot indicates to use /proc. Note that this mode may be more // expensive because we have to take steps to try to avoid leaking unmasked // procfs handles, so you should use [ProcBaseSelf] if you can. ProcRoot = ProcBase{/* contains filtered or unexported fields */} // ProcSelf indicates to use /proc/self. For most programs, this is the // standard choice. ProcSelf = ProcBase{/* contains filtered or unexported fields */} // ProcThreadSelf indicates to use /proc/thread-self. In multi-threaded // programs where one thread has a different CLONE_FS, it is possible for // /proc/self to point the wrong thread and so /proc/thread-self may be // necessary. ProcThreadSelf = ProcBase{/* contains filtered or unexported fields */} )
Functions ¶
func UnmaskedProcRoot ¶
func UnmaskedProcRoot(how *libpathrs.ProcfsOpenHow) error
UnmaskedProcRoot can be passed to Open to request an unmasked procfs handle be created.
procfs, err := procfs.OpenRoot(procfs.UnmaskedProcRoot)
Types ¶
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle is a wrapper around an *os.File handle to "/proc", which can be used to do further procfs-related operations in a safe way.
func Open ¶
func Open(opts ...OpenOption) (*Handle, error)
Open creates a new Handle to a safe "/proc", based on the passed configuration options (in the form of a series of [OpenOption]s).
func (*Handle) Close ¶
Close releases all internal resources for this Handle.
Note that if the handle is actually the global cached handle, this operation is a no-op.
func (*Handle) OpenPid ¶
OpenPid safely opens a given path from inside /proc/$pid/, where pid can be either a PID or TID.
This is effectively equivalent to calling Handle.OpenRoot with the pid prefixed to the subpath.
Be aware that due to PID recycling, using this is generally not safe except in certain circumstances. See the documentation of ProcPid for more details.
func (*Handle) OpenRoot ¶
OpenRoot safely opens a given path from inside /proc/.
This function must only be used for accessing global information from procfs (such as /proc/cpuinfo) or information about other processes (such as /proc/1). Accessing your own process information should be done using Handle.OpenSelf or Handle.OpenThreadSelf.
func (*Handle) OpenSelf ¶
OpenSelf safely opens a given path from inside /proc/self/.
This method is recommend for getting process information about the current process for almost all Go processes *except* for cases where there are runtime.LockOSThread threads that have changed some aspect of their state (such as through unshare(CLONE_FS) or changing namespaces).
For such non-heterogeneous processes, /proc/self may reference to a task that has different state from the current goroutine and so it may be preferable to use Handle.OpenThreadSelf. The same is true if a user really wants to inspect the current OS thread's information (such as /proc/thread-self/stack or /proc/thread-self/status which is always uniquely per-thread).
Unlike Handle.OpenThreadSelf, this method does not involve locking the goroutine to the current OS thread and so is simpler to use and theoretically has slightly less overhead.
func (*Handle) OpenThreadSelf ¶
OpenThreadSelf safely opens a given path from inside /proc/thread-self/.
Most Go processes have heterogeneous threads (all threads have most of the same kernel state such as CLONE_FS) and so Handle.OpenSelf is preferable for most users.
For non-heterogeneous threads, or users that actually want thread-specific information (such as /proc/thread-self/stack or /proc/thread-self/status), this method is necessary.
Because Go can change the running OS thread of your goroutine without notice (and then subsequently kill the old thread), this method will lock the current goroutine to the OS thread (with runtime.LockOSThread) and the caller is responsible for unlocking the the OS thread with the ThreadCloser callback once they are done using the returned file. This callback MUST be called AFTER you have finished using the returned os.File. This callback is completely separate to os.File.Close, so it must be called regardless of how you close the handle.
func (*Handle) Readlink ¶
Readlink safely reads the contents of a symlink from the given procfs base.
This is effectively equivalent to doing an Open*(O_PATH|O_NOFOLLOW) of the path and then doing unix.Readlinkat(fd, ""), but with the benefit that thread locking is not necessary for ProcThreadSelf.
type OpenOption ¶
type OpenOption func(*libpathrs.ProcfsOpenHow) error
OpenOption is a configuration function passed as an argument to Open.
type ProcBase ¶
type ProcBase struct {
// contains filtered or unexported fields
}
ProcBase is used with [ProcReadlink] and related functions to indicate what /proc subpath path operations should be done relative to.
func ProcPid ¶
ProcPid returns a ProcBase which indicates to use /proc/$pid for the given PID (or TID). Be aware that due to PID recycling, using this is generally not safe except in certain circumstances. Namely:
- PID 1 (the init process), as that PID cannot ever get recycled.
- Your current PID (though you should just use [ProcBaseSelf]).
- Your current TID if you have used runtime.LockOSThread (though you should just use [ProcBaseThreadSelf]).
- PIDs of child processes (as long as you are sure that no other part of your program incorrectly catches or ignores SIGCHLD, and that you do it *before* you call wait(2)or any equivalent method that could reap zombies).
type ThreadCloser ¶
type ThreadCloser func()
ThreadCloser is a callback that needs to be called when you are done operating on an os.File fetched using Handle.OpenThreadSelf.
Source Files