[PATCH 1/1] sandbox: fix function descriptions in os.h

[Heinrich Schuchardt]

On 11/6/22 01:37, Pali Rohár wrote:
> On Sunday 06 November 2022 00:44:53 Heinrich Schuchardt wrote:
>> alarm(), read(), write(), ... are not system calls but POSIX functions.
> 
> Well, read() and write() are system calls as opposite of the printf()

read() and write() are library functions on all POSIX system. If a 
system call with the same name exists and is used depends on the 
operating system.

The U-Boot sandbox should not assume to be running on Linux. Nor should 
its documentation make such an assumption.

Best regards

Heinrich

> which is library function. But on every modern operating system there is
> wrapper function in standard (C) library for most system calls. Even
> when calling wrapper function for system call, people still use to say
> "system call". I'm not sure if it makes sense to start renaming every
> string "system call" by "function".
> 
> I think that for sleep() it makes sense to call it a function as on
> some POSIX systems it may be either more sophistic userspace
> implementation (busy loop or SIGALRM + handler) and on other system it
> may be pure system call. But read() is always entry to kernel as a
> system call.
> 
> Also Linux manpages are split between sections 2 and 3, to distinguish
> which are system calls and which are functions.
> 
>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
>> ---
>>   include/os.h | 16 ++++++++--------
>>   1 file changed, 8 insertions(+), 8 deletions(-)
>>
>> diff --git a/include/os.h b/include/os.h
>> index 54874f5e0e..b62d8bbd66 100644
>> --- a/include/os.h
>> +++ b/include/os.h
>> @@ -24,7 +24,7 @@ struct sandbox_state;
>>   int os_printf(const char *format, ...);
>>   
>>   /**
>> - * Access to the OS read() system call
>> + * Access to the OS read() function
>>    *
>>    * @fd:		File descriptor as returned by os_open()
>>    * @buf:	Buffer to place data
>> @@ -34,7 +34,7 @@ int os_printf(const char *format, ...);
>>   ssize_t os_read(int fd, void *buf, size_t count);
>>   
>>   /**
>> - * Access to the OS write() system call
>> + * Access to the OS write() function
>>    *
>>    * @fd:		File descriptor as returned by os_open()
>>    * @buf:	Buffer containing data to write
>> @@ -44,7 +44,7 @@ ssize_t os_read(int fd, void *buf, size_t count);
>>   ssize_t os_write(int fd, const void *buf, size_t count);
>>   
>>   /**
>> - * Access to the OS lseek() system call
>> + * Access to the OS lseek() function
>>    *
>>    * @fd:		File descriptor as returned by os_open()
>>    * @offset:	File offset (based on whence)
>> @@ -67,7 +67,7 @@ off_t os_lseek(int fd, off_t offset, int whence);
>>   int os_filesize(int fd);
>>   
>>   /**
>> - * Access to the OS open() system call
>> + * Access to the OS open() function
>>    *
>>    * @pathname:	Pathname of file to open
>>    * @flags:	Flags, like OS_O_RDONLY, OS_O_RDWR
>> @@ -83,7 +83,7 @@ int os_open(const char *pathname, int flags);
>>   #define OS_O_TRUNC	01000
>>   
>>   /**
>> - * os_close() - access to the OS close() system call
>> + * os_close() - access to the OS close() function
>>    *
>>    * @fd:		File descriptor to close
>>    * Return:	0 on success, -1 on error
>> @@ -91,7 +91,7 @@ int os_open(const char *pathname, int flags);
>>   int os_close(int fd);
>>   
>>   /**
>> - * os_unlink() - access to the OS unlink() system call
>> + * os_unlink() - access to the OS unlink() function
>>    *
>>    * @pathname:	Path of file to delete
>>    * Return:	0 for success, other for error
>> @@ -99,7 +99,7 @@ int os_close(int fd);
>>   int os_unlink(const char *pathname);
>>   
>>   /**
>> - * os_exit() - access to the OS exit() system call
>> + * os_exit() - access to the OS exit() function
>>    *
>>    * This exits with the supplied return code, which should be 0 to indicate
>>    * success.
>> @@ -109,7 +109,7 @@ int os_unlink(const char *pathname);
>>   void os_exit(int exit_code) __attribute__((noreturn));
>>   
>>   /**
>> - * os_alarm() - access to the OS alarm() system call
>> + * os_alarm() - access to the OS alarm() function
>>    */
>>   unsigned int os_alarm(unsigned int seconds);
>>   
>> -- 
>> 2.37.2
>>