basis/unix/users/users-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax io.streams.string kernel quotations sequences strings math ;
   4 IN: unix.users
   5
   6 HELP: all-users
   7 { $values { "seq" sequence } }
   8 { $description "Returns a sequence of high-level " { $link passwd } " tuples that are platform-dependent and field for field complete with the Unix " { $link passwd } " structure." } ;
   9
  10 HELP: effective-user-name
  11 { $values { "string" string } }
  12 { $description "Returns the effective user-name for the current user." } ;
  13
  14 HELP: effective-user-id
  15 { $values { "id" integer } }
  16 { $description "Returns the effective user-name id for the current user." } ;
  17
  18 HELP: new-passwd
  19 { $values { "passwd" passwd } }
  20 { $description "Creates a new passwd tuple dependent on the operating system." } ;
  21
  22 HELP: passwd
  23 { $description "A platform-specific tuple correspding to every field from the Unix passwd struct. BSD passwd structures have four extra slots: " { $slot "change" } ", " { $slot "class" } "," { $slot "expire" } ", " { $slot "fields" } "." } ;
  24
  25 HELP: user-cache
  26 { $description "A symbol storing passwd structures indexed by user-ids when within a " { $link with-user-cache } "." } ;
  27
  28 HELP: passwd>new-passwd
  29 { $values
  30      { "passwd" "a passwd struct" }
  31      { "new-passwd" "a passwd tuple" } }
  32 { $description "A platform-specific conversion routine from a passwd structure to a passwd tuple." } ;
  33
  34 HELP: real-user-name
  35 { $values { "string" string } }
  36 { $description "The real user-name of the current user." } ;
  37
  38 HELP: real-user-id
  39 { $values { "id" integer } }
  40 { $description "The real user id of the current user." } ;
  41
  42 HELP: set-effective-user
  43 { $values { "string/id" "a string or a user id" } }
  44 { $description "Sets the current effective user given a user-name or a user id." } ;
  45
  46 HELP: set-real-user
  47 { $values { "string/id" "a string or a user id" } }
  48 { $description "Sets the current real user given a user-name or a user id." } ;
  49
  50 HELP: user-passwd
  51 { $values
  52      { "obj" object }
  53      { "passwd/f" "passwd or f" } }
  54 { $description "Returns the passwd tuple given a user-name string or user id." } ;
  55
  56 HELP: user-name
  57 { $values
  58      { "id" integer }
  59      { "string" string } }
  60 { $description "Returns the user-name associated with the user id." } ;
  61
  62 HELP: user-id
  63 { $values
  64      { "string" string }
  65      { "id" integer } }
  66 { $description "Returns the user id associated with the user-name." } ;
  67
  68 HELP: with-effective-user
  69 { $values
  70      { "string/id" "a string or a uid" } { "quot" quotation } }
  71 { $description "Sets the effective user-name and calls the quotation. Restores the current user-name on success or on error after the call." } ;
  72
  73 HELP: with-user-cache
  74 { $values
  75      { "quot" quotation } }
  76 { $description "Iterates over the password file using library calls and creates a cache in the " { $link user-cache } " symbol. The cache is a hashtable indexed by user id. When looking up many users, this approach is much faster than calling system calls." } ;
  77
  78 HELP: with-real-user
  79 { $values
  80      { "string/id" "a string or a uid" } { "quot" quotation } }
  81 { $description "Sets the real user-name and calls the quotation. Restores the current user-name on success or on error after the call." } ;
  82
  83 {
  84     real-user-name real-user-id set-real-user
  85     effective-user-name effective-user-id
  86     set-effective-user
  87 } related-words
  88
  89 ARTICLE: "unix.users" "Unix users"
  90 "The " { $vocab-link "unix.users" } " vocabulary contains words that return information about Unix users."
  91 $nl
  92 "Listing all users:"
  93 { $subsections all-users }
  94 "Real user:"
  95 { $subsections
  96     real-user-name
  97     real-user-id
  98     set-real-user
  99 }
 100 "Effective user:"
 101 { $subsections
 102     effective-user-name
 103     effective-user-id
 104     set-effective-user
 105 }
 106 "Combinators to change users:"
 107 { $subsections
 108     with-real-user
 109     with-effective-user
 110 } ;
 111
 112 ABOUT: "unix.users"