basis/elevate/elevate-docs.factor

   1 USING: arrays elevate.private help.markup help.syntax
   2 io.launcher kernel strings system ;
   3
   4 IN: elevate
   5
   6 ABOUT: elevate
   7
   8 ARTICLE: "elevate" "Elevated permissions API"
   9     "Ported from " { $url "https://github.com/barneygale/elevate" "Barney Gale's implementation" } " in Python."
  10     { $subsections elevate elevated lowered }
  11 ;
  12
  13 HELP: elevated
  14 { $values { "command" { $or array string } } { "replace?" boolean } { "win-console?" boolean } { "posix-graphical" boolean } }
  15 { $description
  16     "Spawn a process from the command " { $snippet "command" } " with superuser (administrator) privileges. If the calling process does not already have superuser privileges, it will request them by a number of platform-specific methods."
  17     $nl
  18     "If " { $snippet "replace?" } " is " { $link t } ", the calling Factor process will be replaced with the command (but see Notes)."
  19     $nl
  20     "Windows-specific: If " { $snippet "win-console?" } " is " { $link t } ", a new console window will " { $emphasis "always" } " be spawned for the resulting process, regardless of " { $snippet "replace?" } "."
  21     $nl
  22     "Mac and Linux-specific: If " { $snippet "posix-graphical?" } " is " { $link t } ", a graphical password method will be attempted before " { $snippet "sudo" } "."
  23     $nl
  24     "If the calling process is already run as superuser, nothing happens. The input command is left on the stack, placed into a "{ $link process } " inside an "{ $link array } "."
  25 }
  26 { $notes
  27     { $list
  28         { "On Windows, " { $snippet "replace?" } " has the effect of killing (with " { $link exit } ") the calling process after spawning the command because there is no " { $snippet "exec" } " equivalent in Windows." }
  29     }
  30 }
  31 { $errors
  32     { $link elevated-failed } " when all strategies fail."
  33     $nl
  34     "Any errors thrown by " { $link run-process } "."
  35 } ;
  36
  37 HELP: elevate
  38 { $values { "win-console?" boolean } { "posix-graphical" boolean } }
  39 { $description "Relaunch the current Factor process with superuser privileges. See " { $link elevated } " for an explanation, as the semantics are identical." } ;
  40
  41 HELP: lowered
  42 { $description "Give up all superuser rights, returning a process to normal userspace."
  43 { $notes "If the process is running as \"real superuser\", (not an impersonation), nothing happens." $nl "If the process is running as an unprivileged user, nothing happens." }
  44 }
  45 { $errors { $link lowered-failed } " when giving up superuser rights failed." } ;