basis/io/files/info/unix/unix-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: calendar help.markup help.syntax io.files.info kernel
   4 math strings ;
   5 IN: io.files.info.unix
   6
   7 HELP: add-file-permissions
   8 { $values
   9     { "path" "a pathname string" }
  10     { "n" integer } }
  11 { $description "Ensures that the bits from " { $snippet "n" } " are set in the Unix file permissions for a given file." } ;
  12
  13 HELP: remove-file-permissions
  14 { $values
  15     { "path" "a pathname string" }
  16     { "n" integer } }
  17 { $description "Ensures that the bits from " { $snippet "n" } " are cleared in the Unix file permissions for a given file." } ;
  18
  19 HELP: file-group-id
  20 { $values
  21     { "path" "a pathname string" }
  22     { "gid" integer } }
  23 { $description "Returns the group id for a given file." } ;
  24
  25 HELP: file-group-name
  26 { $values
  27     { "path" "a pathname string" }
  28     { "string" string } }
  29 { $description "Returns the group name for a given file." } ;
  30
  31 HELP: file-permissions
  32 { $values
  33     { "path" "a pathname string" }
  34     { "n" integer } }
  35 { $description "Returns the Unix file permissions for a given file." } ;
  36
  37 HELP: file-user-name
  38 { $values
  39     { "path" "a pathname string" }
  40     { "string" string } }
  41 { $description "Returns the user-name for a given file." } ;
  42
  43 HELP: file-user-id
  44 { $values
  45     { "path" "a pathname string" }
  46     { "uid" integer } }
  47 { $description "Returns the user id for a given file." } ;
  48
  49 HELP: group-execute?
  50 { $values
  51     { "obj" "a pathname string or an integer" }
  52     { "?" boolean } }
  53 { $description "Tests whether the " { $snippet "group execute" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
  54
  55 HELP: group-read?
  56 { $values
  57     { "obj" "a pathname string, file-info object, or an integer" }
  58     { "?" boolean } }
  59 { $description "Tests whether the " { $snippet "group read" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
  60
  61 HELP: group-write?
  62 { $values
  63     { "obj" "a pathname string, file-info object, or an integer" }
  64     { "?" boolean } }
  65 { $description "Tests whether the " { $snippet "group write" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
  66
  67 HELP: other-execute?
  68 { $values
  69     { "obj" "a pathname string, file-info object, or an integer" }
  70     { "?" boolean } }
  71 { $description "Tests whether the " { $snippet "other execute" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
  72
  73 HELP: other-read?
  74 { $values
  75     { "obj" "a pathname string, file-info object, or an integer" }
  76     { "?" boolean } }
  77 { $description "Tests whether the " { $snippet "other read" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
  78
  79 HELP: other-write?
  80 { $values
  81     { "obj" "a pathname string, file-info object, or an integer" }
  82     { "?" boolean } }
  83 { $description "Tests whether the " { $snippet "other write" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
  84
  85 HELP: set-file-access-time
  86 { $values
  87     { "path" "a pathname string" } { "timestamp" timestamp } }
  88 { $description "Sets a file's last access timestamp." } ;
  89
  90 HELP: set-file-group
  91 { $values
  92     { "path" "a pathname string" } { "string/id" "a string or a group id" } }
  93 { $description "Sets a file's group id from the given group id or group name." } ;
  94
  95 HELP: set-file-ids
  96 { $values
  97     { "path" "a pathname string" } { "uid" integer } { "gid" integer } }
  98 { $description "Sets the user id and group id of a file with a single library call." } ;
  99
 100 HELP: set-file-permissions
 101 { $values
 102     { "path" "a pathname string" } { "n" "an integer, interepreted as a string of bits" } }
 103 { $description "Sets the file permissions for a given file with the supplied Unix permissions integer." }
 104 { $examples "Using the traditional octal value:"
 105     { $code "USING: io.files.info.unix kernel ;"
 106         "\"resource:LICENSE.txt\" 0o755 set-file-permissions"
 107     }
 108     "Higher-level, setting named bits:"
 109     { $code "USING: io.files.info.unix kernel literals ;"
 110     "\"resource:LICENSE.txt\""
 111     "flags{ USER-ALL GROUP-READ GROUP-EXECUTE OTHER-READ OTHER-EXECUTE }"
 112     "set-file-permissions"
 113     }
 114 } ;
 115
 116 HELP: set-file-times
 117 { $values
 118     { "path" "a pathname string" } { "timestamps" "an array of two timestamps" } }
 119 { $description "Sets the access and write timestamps for a file as provided in the input array. A value of " { $link f } " provided for either of the timestamps will not change that timestamp." } ;
 120
 121 HELP: set-file-user
 122 { $values
 123     { "path" "a pathname string" } { "string/id" "a string or a user id" } }
 124 { $description "Sets a file's user id from the given user id or user-name." } ;
 125
 126 HELP: set-file-modified-time
 127 { $values
 128     { "path" "a pathname string" } { "timestamp" timestamp } }
 129 { $description "Sets a file's last modified timestamp, or write timestamp." } ;
 130
 131 HELP: set-gid
 132 { $values
 133     { "path" "a pathname string" } { "?" boolean } }
 134 { $description "Sets the " { $snippet "gid" } " bit of a file to true or false." } ;
 135
 136 HELP: gid?
 137 { $values
 138     { "obj" "a pathname string, file-info object, or an integer" }
 139     { "?" boolean } }
 140 { $description "Tests whether the " { $snippet "gid" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
 141
 142 HELP: set-group-execute
 143 { $values
 144     { "path" "a pathname string" } { "?" boolean } }
 145 { $description "Sets the " { $snippet "group execute" } " bit of a file to true or false." } ;
 146
 147 HELP: set-group-read
 148 { $values
 149     { "path" "a pathname string" } { "?" boolean } }
 150 { $description "Sets the " { $snippet "group read" } " bit of a file to true or false." } ;
 151
 152 HELP: set-group-write
 153 { $values
 154     { "path" "a pathname string" } { "?" boolean } }
 155 { $description "Sets the " { $snippet "group write" } " bit of a file to true or false." } ;
 156
 157 HELP: set-other-execute
 158 { $values
 159     { "path" "a pathname string" } { "?" boolean } }
 160 { $description "Sets the " { $snippet "other execute" } " bit of a file to true or false." } ;
 161
 162 HELP: set-other-read
 163 { $values
 164     { "path" "a pathname string" } { "?" boolean } }
 165 { $description "Sets the " { $snippet "other read" } " bit of a file to true or false." } ;
 166
 167 HELP: set-other-write
 168 { $values
 169     { "path" "a pathname string" } { "?" boolean } }
 170 { $description "Sets the " { $snippet "other execute" } " bit of a file to true or false." } ;
 171
 172 HELP: set-sticky
 173 { $values
 174     { "path" "a pathname string" } { "?" boolean } }
 175 { $description "Sets the " { $snippet "sticky" } " bit of a file to true or false." } ;
 176
 177 HELP: sticky?
 178 { $values
 179     { "obj" "a pathname string, file-info object, or an integer" }
 180     { "?" boolean } }
 181 { $description "Tests whether the " { $snippet "sticky" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
 182
 183 HELP: set-uid
 184 { $values
 185     { "path" "a pathname string" } { "?" boolean } }
 186 { $description "Sets the " { $snippet "uid" } " bit of a file to true or false." } ;
 187
 188 HELP: uid?
 189 { $values
 190     { "obj" "a pathname string, file-info object, or an integer" }
 191     { "?" boolean } }
 192 { $description "Tests whether the " { $snippet "uid" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
 193
 194 HELP: set-user-execute
 195 { $values
 196     { "path" "a pathname string" } { "?" boolean } }
 197 { $description "Sets the " { $snippet "user execute" } " bit of a file to true or false." } ;
 198
 199 HELP: set-user-read
 200 { $values
 201     { "path" "a pathname string" } { "?" boolean } }
 202 { $description "Sets the " { $snippet "user read" } " bit of a file to true or false." } ;
 203
 204 HELP: set-user-write
 205 { $values
 206     { "path" "a pathname string" } { "?" boolean } }
 207 { $description "Sets the " { $snippet "user write" } " bit of a file to true or false." } ;
 208
 209 HELP: user-execute?
 210 { $values
 211     { "obj" "a pathname string, file-info object, or an integer" }
 212     { "?" boolean } }
 213 { $description "Tests whether the " { $snippet "user execute" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
 214
 215 HELP: user-read?
 216 { $values
 217     { "obj" "a pathname string, file-info object, or an integer" }
 218     { "?" boolean } }
 219 { $description "Tests whether the " { $snippet "user read" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
 220
 221 HELP: user-write?
 222 { $values
 223     { "obj" "a pathname string, file-info object, or an integer" }
 224     { "?" boolean } }
 225 { $description "Tests whether the " { $snippet "user write" } " bit is set on a file, " { $link file-info } ", or an integer." } ;
 226
 227 ARTICLE: "unix-file-permissions" "Unix file permissions"
 228 "Reading all file permissions:"
 229 { $subsections file-permissions }
 230 "Reading individual file permissions:"
 231 { $subsections
 232     uid?
 233     gid?
 234     sticky?
 235     user-read?
 236     user-write?
 237     user-execute?
 238     group-read?
 239     group-write?
 240     group-execute?
 241     other-read?
 242     other-write?
 243     other-execute?
 244 }
 245 "Changing file permissions:"
 246 { $subsections
 247     add-file-permissions
 248     remove-file-permissions
 249     set-file-permissions
 250 }
 251 "Writing individual file permissions:"
 252 { $subsections
 253     set-uid
 254     set-gid
 255     set-sticky
 256     set-user-read
 257     set-user-write
 258     set-user-execute
 259     set-group-read
 260     set-group-write
 261     set-group-execute
 262     set-other-read
 263     set-other-write
 264     set-other-execute
 265 } ;
 266
 267 ARTICLE: "unix-file-timestamps" "Unix file timestamps"
 268 "To read file times, use the accessors on the object returned by the " { $link file-info } " word." $nl
 269 "Setting multiple file times:"
 270 { $subsections set-file-times }
 271 "Setting just the last access time:"
 272 { $subsections set-file-access-time }
 273 "Setting just the last modified time:"
 274 { $subsections set-file-modified-time } ;
 275
 276
 277 ARTICLE: "unix-file-ids" "Unix file user and group ids"
 278 "Reading file user data:"
 279 { $subsections
 280     file-user-id
 281     file-user-name
 282 }
 283 "Setting file user data:"
 284 { $subsections set-file-user }
 285 "Reading file group data:"
 286 { $subsections
 287     file-group-id
 288     file-group-name
 289 }
 290 "Setting file group data:"
 291 { $subsections set-file-group } ;
 292
 293
 294 ARTICLE: "io.files.info.unix" "Unix file attributes"
 295 "The " { $vocab-link "io.files.info.unix" } " vocabulary implements a high-level way to set Unix-specific permissions, timestamps, and user and group IDs for files."
 296 { $subsections
 297     "unix-file-permissions"
 298     "unix-file-timestamps"
 299     "unix-file-ids"
 300 } ;
 301
 302 ABOUT: "io.files.info.unix"