summaryrefslogtreecommitdiff
path: root/vendor/github.com/nxadm/tail/tail.go
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/github.com/nxadm/tail/tail.go')
-rw-r--r--vendor/github.com/nxadm/tail/tail.go73
1 files changed, 44 insertions, 29 deletions
diff --git a/vendor/github.com/nxadm/tail/tail.go b/vendor/github.com/nxadm/tail/tail.go
index 58d3c4b95..37ea4411e 100644
--- a/vendor/github.com/nxadm/tail/tail.go
+++ b/vendor/github.com/nxadm/tail/tail.go
@@ -1,6 +1,12 @@
+// Copyright (c) 2019 FOSS contributors of https://github.com/nxadm/tail
// Copyright (c) 2015 HPE Software Inc. All rights reserved.
// Copyright (c) 2013 ActiveState Software Inc. All rights reserved.
+//nxadm/tail provides a Go library that emulates the features of the BSD `tail`
+//program. The library comes with full support for truncation/move detection as
+//it is designed to work with log rotation tools. The library works on all
+//operating systems supported by Go, including POSIX systems like Linux and
+//*BSD, and MS Windows. Go 1.9 is the oldest compiler release supported.
package tail
import (
@@ -22,26 +28,31 @@ import (
)
var (
+ // ErrStop is returned when the tail of a file has been marked to be stopped.
ErrStop = errors.New("tail should now stop")
)
type Line struct {
- Text string
- Num int
- SeekInfo SeekInfo
- Time time.Time
- Err error // Error from tail
+ Text string // The contents of the file
+ Num int // The line number
+ SeekInfo SeekInfo // SeekInfo
+ Time time.Time // Present time
+ Err error // Error from tail
}
-// NewLine returns a Line with present time.
+// Deprecated: this function is no longer used internally and it has little of no
+// use in the API. As such, it will be removed from the API in a future major
+// release.
+//
+// NewLine returns a * pointer to a Line struct.
func NewLine(text string, lineNum int) *Line {
return &Line{text, lineNum, SeekInfo{}, time.Now(), nil}
}
-// SeekInfo represents arguments to `io.Seek`
+// SeekInfo represents arguments to io.Seek. See: https://golang.org/pkg/io/#SectionReader.Seek
type SeekInfo struct {
Offset int64
- Whence int // io.Seek*
+ Whence int
}
type logger interface {
@@ -59,26 +70,28 @@ type logger interface {
// Config is used to specify how a file must be tailed.
type Config struct {
// File-specifc
- Location *SeekInfo // Seek to this location before tailing
- ReOpen bool // Reopen recreated files (tail -F)
- MustExist bool // Fail early if the file does not exist
- Poll bool // Poll for file changes instead of using inotify
- Pipe bool // Is a named pipe (mkfifo)
- RateLimiter *ratelimiter.LeakyBucket
+ Location *SeekInfo // Tail from this location. If nil, start at the beginning of the file
+ ReOpen bool // Reopen recreated files (tail -F)
+ MustExist bool // Fail early if the file does not exist
+ Poll bool // Poll for file changes instead of using the default inotify
+ Pipe bool // The file is a named pipe (mkfifo)
// Generic IO
Follow bool // Continue looking for new lines (tail -f)
MaxLineSize int // If non-zero, split longer lines into multiple lines
- // Logger, when nil, is set to tail.DefaultLogger
- // To disable logging: set field to tail.DiscardingLogger
+ // Optionally, use a ratelimiter (e.g. created by the ratelimiter/NewLeakyBucket function)
+ RateLimiter *ratelimiter.LeakyBucket
+
+ // Optionally use a Logger. When nil, the Logger is set to tail.DefaultLogger.
+ // To disable logging, set it to tail.DiscardingLogger
Logger logger
}
type Tail struct {
- Filename string
- Lines chan *Line
- Config
+ Filename string // The filename
+ Lines chan *Line // A consumable channel of *Line
+ Config // Tail.Configuration
file *os.File
reader *bufio.Reader
@@ -93,16 +106,17 @@ type Tail struct {
}
var (
- // DefaultLogger is used when Config.Logger == nil
+ // DefaultLogger logs to os.Stderr and it is used when Config.Logger == nil
DefaultLogger = log.New(os.Stderr, "", log.LstdFlags)
// DiscardingLogger can be used to disable logging output
DiscardingLogger = log.New(ioutil.Discard, "", 0)
)
-// TailFile begins tailing the file. Output stream is made available
-// via the `Tail.Lines` channel. To handle errors during tailing,
-// invoke the `Wait` or `Err` method after finishing reading from the
-// `Lines` channel.
+// TailFile begins tailing the file. And returns a pointer to a Tail struct
+// and an error. An output stream is made available via the Tail.Lines
+// channel (e.g. to be looped and printed). To handle errors during tailing,
+// after finishing reading from the Lines channel, invoke the `Wait` or `Err`
+// method on the returned *Tail.
func TailFile(filename string, config Config) (*Tail, error) {
if config.ReOpen && !config.Follow {
util.Fatal("cannot set ReOpen without Follow.")
@@ -138,10 +152,9 @@ func TailFile(filename string, config Config) (*Tail, error) {
return t, nil
}
-// Tell returns the file's current position, like stdio's ftell().
-// But this value is not very accurate.
-// One line from the chan(tail.Lines) may have been read,
-// so it may have lost one line.
+// Tell returns the file's current position, like stdio's ftell() and an error.
+// Beware that this value may not be completely accurate because one line from
+// the chan(tail.Lines) may have been read already.
func (tail *Tail) Tell() (offset int64, err error) {
if tail.file == nil {
return
@@ -167,7 +180,8 @@ func (tail *Tail) Stop() error {
return tail.Wait()
}
-// StopAtEOF stops tailing as soon as the end of the file is reached.
+// StopAtEOF stops tailing as soon as the end of the file is reached. The function
+// returns an error,
func (tail *Tail) StopAtEOF() error {
tail.Kill(errStopAtEOF)
return tail.Wait()
@@ -435,6 +449,7 @@ func (tail *Tail) sendLine(line string) bool {
// Cleanup removes inotify watches added by the tail package. This function is
// meant to be invoked from a process's exit handler. Linux kernel may not
// automatically remove inotify watches after the process exits.
+// If you plan to re-read a file, don't call Cleanup in between.
func (tail *Tail) Cleanup() {
watch.Cleanup(tail.Filename)
}