libgo/go/os/doc.go

   1 // Copyright 2012 The Go Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 package os
   6
   7 import "time"
   8
   9 // FindProcess looks for a running process by its pid.
  10 //
  11 // The Process it returns can be used to obtain information
  12 // about the underlying operating system process.
  13 //
  14 // On Unix systems, FindProcess always succeeds and returns a Process
  15 // for the given pid, regardless of whether the process exists.
  16 func FindProcess(pid int) (*Process, error) {
  17         return findProcess(pid)
  18 }
  19
  20 // StartProcess starts a new process with the program, arguments and attributes
  21 // specified by name, argv and attr.
  22 //
  23 // StartProcess is a low-level interface. The os/exec package provides
  24 // higher-level interfaces.
  25 //
  26 // If there is an error, it will be of type *PathError.
  27 func StartProcess(name string, argv []string, attr *ProcAttr) (*Process, error) {
  28         return startProcess(name, argv, attr)
  29 }
  30
  31 // Release releases any resources associated with the Process p,
  32 // rendering it unusable in the future.
  33 // Release only needs to be called if Wait is not.
  34 func (p *Process) Release() error {
  35         return p.release()
  36 }
  37
  38 // Kill causes the Process to exit immediately.
  39 func (p *Process) Kill() error {
  40         return p.kill()
  41 }
  42
  43 // Wait waits for the Process to exit, and then returns a
  44 // ProcessState describing its status and an error, if any.
  45 // Wait releases any resources associated with the Process.
  46 // On most operating systems, the Process must be a child
  47 // of the current process or an error will be returned.
  48 func (p *Process) Wait() (*ProcessState, error) {
  49         return p.wait()
  50 }
  51
  52 // Signal sends a signal to the Process.
  53 // Sending Interrupt on Windows is not implemented.
  54 func (p *Process) Signal(sig Signal) error {
  55         return p.signal(sig)
  56 }
  57
  58 // UserTime returns the user CPU time of the exited process and its children.
  59 func (p *ProcessState) UserTime() time.Duration {
  60         return p.userTime()
  61 }
  62
  63 // SystemTime returns the system CPU time of the exited process and its children.
  64 func (p *ProcessState) SystemTime() time.Duration {
  65         return p.systemTime()
  66 }
  67
  68 // Exited reports whether the program has exited.
  69 func (p *ProcessState) Exited() bool {
  70         return p.exited()
  71 }
  72
  73 // Success reports whether the program exited successfully,
  74 // such as with exit status 0 on Unix.
  75 func (p *ProcessState) Success() bool {
  76         return p.success()
  77 }
  78
  79 // Sys returns system-dependent exit information about
  80 // the process. Convert it to the appropriate underlying
  81 // type, such as syscall.WaitStatus on Unix, to access its contents.
  82 func (p *ProcessState) Sys() interface{} {
  83         return p.sys()
  84 }
  85
  86 // SysUsage returns system-dependent resource usage information about
  87 // the exited process. Convert it to the appropriate underlying
  88 // type, such as *syscall.Rusage on Unix, to access its contents.
  89 // (On Unix, *syscall.Rusage matches struct rusage as defined in the
  90 // getrusage(2) manual page.)
  91 func (p *ProcessState) SysUsage() interface{} {
  92         return p.sysUsage()
  93 }
  94
  95 // Hostname returns the host name reported by the kernel.
  96 func Hostname() (name string, err error) {
  97         return hostname()
  98 }
  99
 100 // Readdir reads the contents of the directory associated with file and
 101 // returns a slice of up to n FileInfo values, as would be returned
 102 // by Lstat, in directory order. Subsequent calls on the same file will yield
 103 // further FileInfos.
 104 //
 105 // If n > 0, Readdir returns at most n FileInfo structures. In this case, if
 106 // Readdir returns an empty slice, it will return a non-nil error
 107 // explaining why. At the end of a directory, the error is io.EOF.
 108 //
 109 // If n <= 0, Readdir returns all the FileInfo from the directory in
 110 // a single slice. In this case, if Readdir succeeds (reads all
 111 // the way to the end of the directory), it returns the slice and a
 112 // nil error. If it encounters an error before the end of the
 113 // directory, Readdir returns the FileInfo read until that point
 114 // and a non-nil error.
 115 func (f *File) Readdir(n int) ([]FileInfo, error) {
 116         if f == nil {
 117                 return nil, ErrInvalid
 118         }
 119         return f.readdir(n)
 120 }
 121
 122 // Readdirnames reads and returns a slice of names from the directory f.
 123 //
 124 // If n > 0, Readdirnames returns at most n names. In this case, if
 125 // Readdirnames returns an empty slice, it will return a non-nil error
 126 // explaining why. At the end of a directory, the error is io.EOF.
 127 //
 128 // If n <= 0, Readdirnames returns all the names from the directory in
 129 // a single slice. In this case, if Readdirnames succeeds (reads all
 130 // the way to the end of the directory), it returns the slice and a
 131 // nil error. If it encounters an error before the end of the
 132 // directory, Readdirnames returns the names read until that point and
 133 // a non-nil error.
 134 func (f *File) Readdirnames(n int) (names []string, err error) {
 135         if f == nil {
 136                 return nil, ErrInvalid
 137         }
 138         return f.readdirnames(n)
 139 }