Merge pull request #241 from sethp-nr/patch-1

sdjournal: clarify documentation's notion of "current"

Author: lucab

sdjournal/journal.go

@@ -648,7 +648,8 @@ func (j *Journal) getData(field string) (unsafe.Pointer, C.int, error) {
 }
 
 // GetData gets the data object associated with a specific field from the
-// current journal entry.
+// the journal entry referenced by the last completed Next/Previous function
+// call. To call GetData, you must have first called one of these functions.
 func (j *Journal) GetData(field string) (string, error) {
 	d, l, err := j.getData(field)
 	if err != nil {
@@ -659,7 +660,9 @@ func (j *Journal) GetData(field string) (string, error) {
 }
 
 // GetDataValue gets the data object associated with a specific field from the
-// current journal entry, returning only the value of the object.
+// journal entry referenced by the last completed Next/Previous function call,
+// returning only the value of the object. To call GetDataValue, you must first
+// have called one of the Next/Previous functions.
 func (j *Journal) GetDataValue(field string) (string, error) {
 	val, err := j.GetData(field)
 	if err != nil {
@@ -670,7 +673,8 @@ func (j *Journal) GetDataValue(field string) (string, error) {
 }
 
 // GetDataBytes gets the data object associated with a specific field from the
-// current journal entry.
+// journal entry referenced by the last completed Next/Previous function call.
+// To call GetDataBytes, you must first have called one of these functions.
 func (j *Journal) GetDataBytes(field string) ([]byte, error) {
 	d, l, err := j.getData(field)
 	if err != nil {
@@ -681,7 +685,9 @@ func (j *Journal) GetDataBytes(field string) ([]byte, error) {
 }
 
 // GetDataValueBytes gets the data object associated with a specific field from the
-// current journal entry, returning only the value of the object.
+// journal entry referenced by the last completed Next/Previous function call,
+// returning only the value of the object. To call GetDataValueBytes, you must first
+// have called one of the Next/Previous functions.
 func (j *Journal) GetDataValueBytes(field string) ([]byte, error) {
 	val, err := j.GetDataBytes(field)
 	if err != nil {
@@ -691,9 +697,10 @@ func (j *Journal) GetDataValueBytes(field string) ([]byte, error) {
 	return bytes.SplitN(val, []byte("="), 2)[1], nil
 }
 
-// GetEntry returns a full representation of a journal entry with
-// all key-value pairs of data as well as address fields (cursor, realtime
-// timestamp and monotonic timestamp)
+// GetEntry returns a full representation of the journal entry referenced by the
+// last completed Next/Previous function call, with all key-value pairs of data
+// as well as address fields (cursor, realtime timestamp and monotonic timestamp).
+// To call GetEntry, you must first have called one of the Next/Previous functions.
 func (j *Journal) GetEntry() (*JournalEntry, error) {
 	sd_journal_get_realtime_usec, err := getFunction("sd_journal_get_realtime_usec")
 	if err != nil {
@@ -802,8 +809,10 @@ func (j *Journal) SetDataThreshold(threshold uint64) error {
 	return nil
 }
 
-// GetRealtimeUsec gets the realtime (wallclock) timestamp of the current
-// journal entry.
+// GetRealtimeUsec gets the realtime (wallclock) timestamp of the journal
+// entry referenced by the last completed Next/Previous function call. To
+// call GetRealtimeUsec, you must first have called one of the Next/Previous
+// functions.
 func (j *Journal) GetRealtimeUsec() (uint64, error) {
 	var usec C.uint64_t
 
@@ -823,7 +832,10 @@ func (j *Journal) GetRealtimeUsec() (uint64, error) {
 	return uint64(usec), nil
 }
 
-// GetMonotonicUsec gets the monotonic timestamp of the current journal entry.
+// GetMonotonicUsec gets the monotonic timestamp of the journal entry
+// referenced by the last completed Next/Previous function call. To call
+// GetMonotonicUsec, you must first have called one of the Next/Previous
+// functions.
 func (j *Journal) GetMonotonicUsec() (uint64, error) {
 	var usec C.uint64_t
 	var boot_id C.sd_id128_t
@@ -844,7 +856,9 @@ func (j *Journal) GetMonotonicUsec() (uint64, error) {
 	return uint64(usec), nil
 }
 
-// GetCursor gets the cursor of the current journal entry.
+// GetCursor gets the cursor of the last journal entry reeferenced by the
+// last completed Next/Previous function call. To call GetCursor, you must
+// first have called one of the Next/Previous functions.
 func (j *Journal) GetCursor() (string, error) {
 	sd_journal_get_cursor, err := getFunction("sd_journal_get_cursor")
 	if err != nil {
@@ -894,7 +908,8 @@ func (j *Journal) TestCursor(cursor string) error {
 }
 
 // SeekHead seeks to the beginning of the journal, i.e. the oldest available
-// entry.
+// entry. This call must be followed by a call to Next before any call to
+// Get* will return data about the first element.
 func (j *Journal) SeekHead() error {
 	sd_journal_seek_head, err := getFunction("sd_journal_seek_head")
 	if err != nil {
@@ -913,7 +928,8 @@ func (j *Journal) SeekHead() error {
 }
 
 // SeekTail may be used to seek to the end of the journal, i.e. the most recent
-// available entry.
+// available entry. This call must be followed by a call to Next before any
+// call to Get* will return data about the last element.
 func (j *Journal) SeekTail() error {
 	sd_journal_seek_tail, err := getFunction("sd_journal_seek_tail")
 	if err != nil {
@@ -932,7 +948,8 @@ func (j *Journal) SeekTail() error {
 }
 
 // SeekRealtimeUsec seeks to the entry with the specified realtime (wallclock)
-// timestamp, i.e. CLOCK_REALTIME.
+// timestamp, i.e. CLOCK_REALTIME. This call must be followed by a call to
+// Next/Previous before any call to Get* will return data about the sought entry.
 func (j *Journal) SeekRealtimeUsec(usec uint64) error {
 	sd_journal_seek_realtime_usec, err := getFunction("sd_journal_seek_realtime_usec")
 	if err != nil {
@@ -950,7 +967,9 @@ func (j *Journal) SeekRealtimeUsec(usec uint64) error {
 	return nil
 }
 
-// SeekCursor seeks to a concrete journal cursor.
+// SeekCursor seeks to a concrete journal cursor. This call must be
+// followed by a call to Next/Previous before any call to Get* will return
+// data about the sought entry.
 func (j *Journal) SeekCursor(cursor string) error {
 	sd_journal_seek_cursor, err := getFunction("sd_journal_seek_cursor")
 	if err != nil {
@@ -1075,7 +1094,9 @@ func (j *Journal) GetUniqueValues(field string) ([]string, error) {
 	return result, nil
 }
 
-// GetCatalog retrieves a message catalog entry for the current journal entry.
+// GetCatalog retrieves a message catalog entry for the journal entry referenced
+// by the last completed Next/Previous function call. To call GetCatalog, you
+// must first have called one of these functions.
 func (j *Journal) GetCatalog() (string, error) {
 	sd_journal_get_catalog, err := getFunction("sd_journal_get_catalog")
 	if err != nil {