xmake-docs/docs/api/scripts/extension-modules/core/base/privilege.md

core.base.privilege

This module provides privilege management for elevated permission operations.

::: tip TIP To use this module, you need to import it first: import("core.base.privilege") :::

This module allows you to store and restore privilege levels when working with operations that require elevated permissions, such as writing to system directories.

::: warning WARNING This module should be used with extreme caution. Privilege escalation operations can be dangerous if misused. :::

privilege.store

• Store current privilege by dropping to original user

Function Prototype

::: tip API

privilege.store()

:::

Parameter Description

No parameters

Return Value

Type	Description
boolean	Returns true if privilege was successfully stored and dropped, false otherwise

Usage

This function should be called early in the process when you have elevated privileges (e.g., running as root or via sudo). It stores the privilege and drops to the original user that started the process.

import("core.base.privilege")

-- When running with elevated privileges, store and drop them
-- This allows the process to run with normal permissions by default
if privilege.store() then
    print("Privilege stored, now running as original user")
end

-- ... later, when privileged operations are needed ...
if privilege.get() then
    -- Perform privileged operations like installing system packages
    os.vrunv("apt", {"install", "-y", "package-name"})
end

::: warning NOTE This function can only succeed if running as root. It attempts to determine the original user from:

1. SUDO_UID and SUDO_GID environment variables (if running via sudo)
2. The owner of the project directory
3. The owner of the current directory :::

privilege.has

• Check if stored privilege is available

Function Prototype

::: tip API

privilege.has()

:::

Parameter Description

No parameters

Return Value

Type	Description
boolean	Returns true if stored privilege is available, false otherwise

Usage

import("core.base.privilege")

if privilege.has() then
    print("Stored privilege is available")
else
    print("No stored privilege")
end

privilege.get

• Restore elevated privilege

Function Prototype

::: tip API

privilege.get()

:::

Parameter Description

No parameters

Return Value

Type	Description
boolean	Returns true if privilege was successfully restored, false otherwise

Usage

This function restores the elevated privileges that were previously stored with privilege.store().

import("core.base.privilege")

-- Check if we have stored privilege
if privilege.has() then
    -- Restore privileged access
    if privilege.get() then
        print("Privilege restored, now running with elevated permissions")
        
        -- Perform privileged operations like installing system packages
        os.vrunv("apt", {"install", "-y", "package-name"})
        
        -- Or write to protected system directories
        os.cp("file.txt", "/etc/some/directory/")
    end
end

::: warning NOTE This function can only succeed if privilege.store() was previously called successfully. It restores root privileges by setting UID and GID to 0. :::