return for a timeout is negative 4

[excaliburtb]

osal/src/os/shared/src/osapi-file.c

Line 208 in afb5f7b

return_code = OS_GenericRead_Impl(&token, buffer, nbytes, timeout);

Not sure which layer of abstraction to report this but the comment states that a timeout should return 0. However, on Linux/portable BSD... the eventual call to OS_DoSelect is returning OS_ERROR_TIMEOUT (-4) and flowing that all the to the OS_TimedRead API. I would prefer it to be "caught" and returned as 0 at some point but.. more than anything.. just need the comment to match.

[jphickey]

Is this the comment you are referring to?

osal/src/os/inc/osapi-file.h

Line 224 in afb5f7b

* @return Byte count on success, zero for timeout, or appropriate error code,

Note that a read of size 0 typically indicates an EOF condition. POSIX says this about read():

No  data transfer shall occur past the current end-of-file. If the starting position is at or after the end-of-file, 0 shall be returned.

This is a paradigm that OSAL is borrowing/passing through here, so returning OS_ERROR_TIMEOUT on timeout is preferable in order to distinguish this as a true timeout, rather than EOF. This is particularly important for sockets where the remote end has closed the connection.

I will update the documentation to correct this. We should probably also add a note that a read of size 0 is the EOF indicator.

[excaliburtb]

yep, the api comments need to not say timeout == 0.

[excaliburtb]

and just to double-check, double-confirm... for TCP sockets the "replacement" for send and recv calls is OS_TimedRead and OS_TimeWrite, correct?

[jphickey]

Yes, Or regular OS_read/OS_write if you don't need a timeout. The SendTo/RecvFrom abstractions are only intended for datagram sockets. Stream sockets should use either form of read/write to transfer data.