[go] syscall: document Sendfile semantics

0 views

Skip to first unread message

Gerrit Bot (Gerrit)

unread,

4:30 PM (2 hours ago) 4:30 PM

to goph...@pubsubhelper.golang.org, Bill Morgan, golang-co...@googlegroups.com

Gerrit Bot has uploaded the change for review

Commit message

syscall: document Sendfile semantics

syscall.Sendfile behavior differs significantly between operating
systems.

Document the platform-specific behavior for the offset argument and
partial write reporting on Linux versus BSD-derived systems.

Fixes #64044

Change-Id: I93f740c3e2df911a10bf0884ffab218d4bb4e5fc

GitHub-Last-Rev: 1537a76cd20f045e07452dbcdba415154baaccfe

GitHub-Pull-Request: golang/go#77224

Change diff

diff --git a/src/syscall/syscall_unix.go b/src/syscall/syscall_unix.go
index d957b77..323d438 100644
--- a/src/syscall/syscall_unix.go
+++ b/src/syscall/syscall_unix.go
@@ -522,6 +522,22 @@
 	return
 }
 
+// Sendfile copies up to count bytes from file descriptor infd to file descriptor outfd.
+//
+// It wraps the sendfile system call. The behavior varies by operating system,
+// particularly regarding the offset argument and how partial writes are reported.
+//
+// On Linux, if offset is nil, Sendfile uses and updates the current file
+// position of infd. If offset is non-nil, the current file position is
+// unchanged, and the offset pointer is updated to reflect the bytes written.
+//
+// On BSD-derived systems (including macOS), the offset argument is not
+// updated by the system call; the caller must manually update the offset
+// using the number of bytes written. These systems may also return a
+// non-zero byte count together with an error (for example, EAGAIN).
+// On Linux, a non-nil error typically implies that no bytes were written.
+//
+// For precise semantics, see the system documentation (e.g., man 2 sendfile).
 func Sendfile(outfd int, infd int, offset *int64, count int) (written int, err error) {
 	if race.Enabled {
 		race.ReleaseMerge(unsafe.Pointer(&ioSync))

Change information

Files:

M src/syscall/syscall_unix.go

Change size: S

Delta: 1 file changed, 16 insertions(+), 0 deletions(-)

Open in Gerrit

Related details

Attention set is empty

Submit Requirements:

Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass

Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings.

Gerrit

unsatisfied_requirement

satisfied_requirement

open

diffy

Ian Lance Taylor (Gerrit)

unread,

6:00 PM (1 hour ago) 6:00 PM

to Bill Morgan, Gerrit Bot, goph...@pubsubhelper.golang.org, Tobias Klauser, Ian Lance Taylor, Brad Fitzpatrick, Gopher Robot, golang-co...@googlegroups.com

Attention needed from Brad Fitzpatrick and Tobias Klauser

Ian Lance Taylor added 3 comments

Patchset-level comments

File-level comment, Patchset 1 (Latest):

Ian Lance Taylor . resolved

Note that for new programs we normally recommend using golang.org/x/sys/unix.Sendfile. Perhaps something like this should be done there.

File src/syscall/syscall_unix.go

Line 534, Patchset 1 (Latest):// On BSD-derived systems (including macOS), the offset argument is not

Ian Lance Taylor . unresolved

This isn't very clear. Like the previous paragraph, it should explain what happens if offset is nil.

Line 536, Patchset 1 (Latest):// using the number of bytes written. These systems may also return a

Ian Lance Taylor . unresolved

The bit starting with "These systems may also" should be in a different paragraph, or the Linux part should move into the preceding paragraph.

Open in Gerrit

Related details

Attention is currently required from:

Brad Fitzpatrick
Tobias Klauser

Submit Requirements:

Code-Review

No-Unresolved-Comments

Review-Enforcement
TryBots-Pass

Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings.

Gerrit

unsatisfied_requirement

open

diffy

Reply all

Reply to author

Forward

0 new messages