authorgravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2020-09-25 18:42:24+02:00
committergravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2020-09-25 18:42:24+02:00
log8d01133bd04423f896dee81b89c56372aa1ee310
treecef13b37bacbf95f0a3feb680735f19ce3595941
parentc196c27af86f0f10b2f53240a68477391c4b9820

update doc comments

Signed-off-by: Loris Cro <kappaloris@gmail.com>

1 files changed, 22 insertions(+), 18 deletions(-)

lib/std/os.zig+22-18
...@@ -314,8 +314,8 @@ pub const ReadError = error{...@@ -314,8 +314,8 @@ pub const ReadError = error{
314314
315/// Returns the number of bytes that were read, which can be less than315/// Returns the number of bytes that were read, which can be less than
316/// buf.len. If 0 bytes were read, that means EOF.316/// buf.len. If 0 bytes were read, that means EOF.
317/// If the application has a global event loop enabled, EAGAIN is handled317/// If `fd` is opened in non blocking mode, the function will return error.WouldBlock
318/// via the event loop. Otherwise EAGAIN results in error.WouldBlock.318/// when EAGAIN is received.
319///319///
320/// Linux has a limit on how many bytes may be transferred in one `read` call, which is `0x7ffff000`320/// Linux has a limit on how many bytes may be transferred in one `read` call, which is `0x7ffff000`
321/// on both 64-bit and 32-bit systems. This is due to using a signed C int as the return value, as321/// on both 64-bit and 32-bit systems. This is due to using a signed C int as the return value, as
...@@ -382,8 +382,8 @@ pub fn read(fd: fd_t, buf: []u8) ReadError!usize {...@@ -382,8 +382,8 @@ pub fn read(fd: fd_t, buf: []u8) ReadError!usize {
382382
383/// Number of bytes read is returned. Upon reading end-of-file, zero is returned.383/// Number of bytes read is returned. Upon reading end-of-file, zero is returned.
384///384///
385/// For POSIX systems, if the application has a global event loop enabled, EAGAIN is handled385/// For POSIX systems, if `fd` is opened in non blocking mode, the function will
386/// via the event loop. Otherwise EAGAIN results in `error.WouldBlock`.386/// return error.WouldBlock when EAGAIN is received.
387/// On Windows, if the application has a global event loop enabled, I/O Completion Ports are387/// On Windows, if the application has a global event loop enabled, I/O Completion Ports are
388/// used to perform the I/O. `error.WouldBlock` is not possible on Windows.388/// used to perform the I/O. `error.WouldBlock` is not possible on Windows.
389///389///
...@@ -440,8 +440,8 @@ pub const PReadError = ReadError || error{Unseekable};...@@ -440,8 +440,8 @@ pub const PReadError = ReadError || error{Unseekable};
440///440///
441/// Retries when interrupted by a signal.441/// Retries when interrupted by a signal.
442///442///
443/// For POSIX systems, if the application has a global event loop enabled, EAGAIN is handled443/// For POSIX systems, if `fd` is opened in non blocking mode, the function will
444/// via the event loop. Otherwise EAGAIN results in `error.WouldBlock`.444/// return error.WouldBlock when EAGAIN is received.
445/// On Windows, if the application has a global event loop enabled, I/O Completion Ports are445/// On Windows, if the application has a global event loop enabled, I/O Completion Ports are
446/// used to perform the I/O. `error.WouldBlock` is not possible on Windows.446/// used to perform the I/O. `error.WouldBlock` is not possible on Windows.
447pub fn pread(fd: fd_t, buf: []u8, offset: u64) PReadError!usize {447pub fn pread(fd: fd_t, buf: []u8, offset: u64) PReadError!usize {
...@@ -571,8 +571,8 @@ pub fn ftruncate(fd: fd_t, length: u64) TruncateError!void {...@@ -571,8 +571,8 @@ pub fn ftruncate(fd: fd_t, length: u64) TruncateError!void {
571///571///
572/// Retries when interrupted by a signal.572/// Retries when interrupted by a signal.
573///573///
574/// For POSIX systems, if the application has a global event loop enabled, EAGAIN is handled574/// For POSIX systems, if `fd` is opened in non blocking mode, the function will
575/// via the event loop. Otherwise EAGAIN results in `error.WouldBlock`.575/// return error.WouldBlock when EAGAIN is received.
576/// On Windows, if the application has a global event loop enabled, I/O Completion Ports are576/// On Windows, if the application has a global event loop enabled, I/O Completion Ports are
577/// used to perform the I/O. `error.WouldBlock` is not possible on Windows.577/// used to perform the I/O. `error.WouldBlock` is not possible on Windows.
578///578///
...@@ -667,8 +667,8 @@ pub const WriteError = error{...@@ -667,8 +667,8 @@ pub const WriteError = error{
667/// another write() call to transfer the remaining bytes. The subsequent call will either667/// another write() call to transfer the remaining bytes. The subsequent call will either
668/// transfer further bytes or may result in an error (e.g., if the disk is now full).668/// transfer further bytes or may result in an error (e.g., if the disk is now full).
669///669///
670/// For POSIX systems, if the application has a global event loop enabled, EAGAIN is handled670/// For POSIX systems, if `fd` is opened in non blocking mode, the function will
671/// via the event loop. Otherwise EAGAIN results in `error.WouldBlock`.671/// return error.WouldBlock when EAGAIN is received.
672/// On Windows, if the application has a global event loop enabled, I/O Completion Ports are672/// On Windows, if the application has a global event loop enabled, I/O Completion Ports are
673/// used to perform the I/O. `error.WouldBlock` is not possible on Windows.673/// used to perform the I/O. `error.WouldBlock` is not possible on Windows.
674///674///
...@@ -747,8 +747,8 @@ pub fn write(fd: fd_t, bytes: []const u8) WriteError!usize {...@@ -747,8 +747,8 @@ pub fn write(fd: fd_t, bytes: []const u8) WriteError!usize {
747/// another write() call to transfer the remaining bytes. The subsequent call will either747/// another write() call to transfer the remaining bytes. The subsequent call will either
748/// transfer further bytes or may result in an error (e.g., if the disk is now full).748/// transfer further bytes or may result in an error (e.g., if the disk is now full).
749///749///
750/// For POSIX systems, if the application has a global event loop enabled, EAGAIN is handled750/// For POSIX systems, if `fd` is opened in non blocking mode, the function will
751/// via the event loop. Otherwise EAGAIN results in `error.WouldBlock`.751/// return error.WouldBlock when EAGAIN is received.k`.
752/// On Windows, if the application has a global event loop enabled, I/O Completion Ports are752/// On Windows, if the application has a global event loop enabled, I/O Completion Ports are
753/// used to perform the I/O. `error.WouldBlock` is not possible on Windows.753/// used to perform the I/O. `error.WouldBlock` is not possible on Windows.
754///754///
...@@ -817,8 +817,8 @@ pub const PWriteError = WriteError || error{Unseekable};...@@ -817,8 +817,8 @@ pub const PWriteError = WriteError || error{Unseekable};
817/// another write() call to transfer the remaining bytes. The subsequent call will either817/// another write() call to transfer the remaining bytes. The subsequent call will either
818/// transfer further bytes or may result in an error (e.g., if the disk is now full).818/// transfer further bytes or may result in an error (e.g., if the disk is now full).
819///819///
820/// For POSIX systems, if the application has a global event loop enabled, EAGAIN is handled820/// For POSIX systems, if `fd` is opened in non blocking mode, the function will
821/// via the event loop. Otherwise EAGAIN results in `error.WouldBlock`.821/// return error.WouldBlock when EAGAIN is received.
822/// On Windows, if the application has a global event loop enabled, I/O Completion Ports are822/// On Windows, if the application has a global event loop enabled, I/O Completion Ports are
823/// used to perform the I/O. `error.WouldBlock` is not possible on Windows.823/// used to perform the I/O. `error.WouldBlock` is not possible on Windows.
824///824///
...@@ -904,8 +904,8 @@ pub fn pwrite(fd: fd_t, bytes: []const u8, offset: u64) PWriteError!usize {...@@ -904,8 +904,8 @@ pub fn pwrite(fd: fd_t, bytes: []const u8, offset: u64) PWriteError!usize {
904/// another write() call to transfer the remaining bytes. The subsequent call will either904/// another write() call to transfer the remaining bytes. The subsequent call will either
905/// transfer further bytes or may result in an error (e.g., if the disk is now full).905/// transfer further bytes or may result in an error (e.g., if the disk is now full).
906///906///
907/// If the application has a global event loop enabled, EAGAIN is handled907/// If `fd` is opened in non blocking mode, the function will
908/// via the event loop. Otherwise EAGAIN results in `error.WouldBlock`.908/// return error.WouldBlock when EAGAIN is received.
909///909///
910/// The following systems do not have this syscall, and will return partial writes if more than one910/// The following systems do not have this syscall, and will return partial writes if more than one
911/// vector is provided:911/// vector is provided:
...@@ -2806,8 +2806,8 @@ pub const AcceptError = error{...@@ -2806,8 +2806,8 @@ pub const AcceptError = error{
2806} || UnexpectedError;2806} || UnexpectedError;
28072807
2808/// Accept a connection on a socket.2808/// Accept a connection on a socket.
2809/// If the application has a global event loop enabled, EAGAIN is handled2809/// If `sockfd` is opened in non blocking mode, the function will
2810/// via the event loop. Otherwise EAGAIN results in error.WouldBlock.2810/// return error.WouldBlock when EAGAIN is received.
2811pub fn accept(2811pub fn accept(
2812 /// This argument is a socket that has been created with `socket`, bound to a local address2812 /// This argument is a socket that has been created with `socket`, bound to a local address
2813 /// with `bind`, and is listening for connections after a `listen`.2813 /// with `bind`, and is listening for connections after a `listen`.
...@@ -3036,6 +3036,8 @@ pub const ConnectError = error{...@@ -3036,6 +3036,8 @@ pub const ConnectError = error{
3036} || UnexpectedError;3036} || UnexpectedError;
30373037
3038/// Initiate a connection on a socket.3038/// Initiate a connection on a socket.
3039/// If `sockfd` is opened in non blocking mode, the function will
3040/// return error.WouldBlock when EAGAIN or EINPROGRESS is received.
3039pub fn connect(sockfd: socket_t, sock_addr: *const sockaddr, len: socklen_t) ConnectError!void {3041pub fn connect(sockfd: socket_t, sock_addr: *const sockaddr, len: socklen_t) ConnectError!void {
3040 if (builtin.os.tag == .windows) {3042 if (builtin.os.tag == .windows) {
3041 const rc = windows.ws2_32.connect(sockfd, sock_addr, len);3043 const rc = windows.ws2_32.connect(sockfd, sock_addr, len);
...@@ -5051,6 +5053,8 @@ pub const RecvFromError = error{...@@ -5051,6 +5053,8 @@ pub const RecvFromError = error{
5051 SystemResources,5053 SystemResources,
5052} || UnexpectedError;5054} || UnexpectedError;
50535055
5056/// If `sockfd` is opened in non blocking mode, the function will
5057/// return error.WouldBlock when EAGAIN is received.
5054pub fn recvfrom(5058pub fn recvfrom(
5055 sockfd: fd_t,5059 sockfd: fd_t,
5056 buf: []u8,5060 buf: []u8,