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

[Pali Rohár]

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()
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
>