StdLib/Include/sys/EfiSysCall.h

   1 /** @file
   2   Function declarations for UEFI "system calls".
   3
   4     The following macros are defined in this file:<BR>
   5 @verbatim
   6       STDIN_FILENO      0     standard input file descriptor
   7       STDOUT_FILENO     1     standard output file descriptor
   8       STDERR_FILENO     2     standard error file descriptor
   9       SEEK_SET          0     set file offset to offset
  10       SEEK_CUR          1     set file offset to current plus offset
  11       SEEK_END          2     set file offset to EOF plus offset
  12       VALID_OPEN        1
  13       VALID_CLOSED      0
  14       VALID_DONT_CARE  -1
  15 @endverbatim
  16
  17     The following types are defined in this file:<BR>
  18 @verbatim
  19       struct stat;    Structure declared in <sys/stat.h>
  20 @endverbatim
  21
  22     The following functions are declared in this file:<BR>
  23 @verbatim
  24       ###############  System Calls used in stdio.
  25       int       close     (int fd);
  26       ssize_t   read      (int fd, void *buf, size_t n);
  27       ssize_t   write     (int fd, const void *buf, size_t n);
  28       int       unlink    (const char *name);
  29       int       dup2      (int, int);
  30       int       rmdir     (const char *);
  31       int       isatty    (int);
  32
  33       ###############  System Calls which are also declared in sys/fcntl.h.
  34       int       open      (const char *name, int oflags, int mode);
  35       int       creat     (const char *, mode_t);
  36       int       fcntl     (int, int, ...);
  37
  38       ###############  System Calls which are also declared in stat.h.
  39       int       mkdir     (const char *, mode_t);
  40       int       fstat     (int, struct stat *);
  41       int       lstat     (const char *, struct stat *);
  42       int       stat      (const char *, void *);
  43       int       chmod     (const char *, mode_t);
  44
  45       ###############  System Calls which are also declared in sys/types.h.
  46       off_t     lseek     (int, off_t, int);
  47       int       truncate  (const char *, off_t);
  48       int       ftruncate (int, off_t);   //  IEEE Std 1003.1b-93
  49
  50       ###############  EFI-specific Functions.
  51       int       DeleteOnClose (int fd);    Mark an open file to be deleted when closed.
  52       int       FindFreeFD    (int MinFd);
  53       BOOLEAN   ValidateFD    (int fd, int IsOpen);
  54 @endverbatim
  55
  56   Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>
  57   This program and the accompanying materials are licensed and made available under
  58   the terms and conditions of the BSD License that accompanies this distribution.
  59   The full text of the license may be found at
  60   http://opensource.org/licenses/bsd-license.
  61
  62   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  63   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  64 **/
  65 #ifndef _EFI_SYS_CALL_H
  66 #define _EFI_SYS_CALL_H
  67
  68 #include  <sys/EfiCdefs.h>
  69 #include  <sys/types.h>
  70
  71 struct stat;  /* Structure declared in <sys/stat.h> */
  72
  73 #define STDIN_FILENO  0 /**< standard input file descriptor */
  74 #define STDOUT_FILENO 1 /**< standard output file descriptor */
  75 #define STDERR_FILENO 2 /**< standard error file descriptor */
  76
  77 /* whence values for lseek(2)
  78    Always ensure that these are consistent with <stdio.h> and <unistd.h>!
  79 */
  80 #ifndef SEEK_SET
  81   #define SEEK_SET  0 /**< set file offset to offset */
  82 #endif
  83 #ifndef SEEK_CUR
  84   #define SEEK_CUR  1 /**< set file offset to current plus offset */
  85 #endif
  86 #ifndef SEEK_END
  87   #define SEEK_END  2 /**< set file offset to EOF plus offset */
  88 #endif
  89
  90 // Parameters for the ValidateFD function.
  91 #define VALID_OPEN         1
  92 #define VALID_CLOSED       0
  93 #define VALID_DONT_CARE   -1
  94
  95 __BEGIN_DECLS
  96 /* EFI versions of BSD system calls used in stdio */
  97
  98   /** Close a file or device.
  99
 100     @param[in]  fd    File Descriptor for the file or device to close.
 101
 102     @retval   0   Successful completion.
 103     @retval  -1   An error occurred, identified by errno.
 104                     - EBADF fd is not a valid File Descriptor.
 105                     - EINTR The function was interrupted by a signal.
 106                     - EIO An I/O error occurred.
 107   **/
 108   int       close     (int fd);
 109
 110   /** Read from a file or device.
 111
 112     @param[in]  fd    File Descriptor for the file or device to read.
 113     @param[in]  buf   Buffer to read data into.
 114     @param[in]  N     Maximum number of bytes to read.
 115
 116     @return   On successful completion, read returns a non-negative integer
 117               indicating the number of bytes actually read.  Otherwise, it
 118               returns -1 and sets errno as follows:
 119                 - EAGAIN
 120                 - EWOULDBLOCK
 121                 - EBADF
 122                 - EBADMSG
 123                 - EINTR
 124                 - EINVAL
 125                 - EIO
 126                 - EISDIR
 127                 - EOVERFLOW
 128                 - ECONNRESET
 129                 - ENOTCONN
 130                 - ETIMEDOUT
 131                 - ENOBUFS
 132                 - ENOMEM
 133                 - ENXIO
 134   **/
 135   ssize_t   read      (int fd, void *buf, size_t n);
 136
 137   /** Write to a file or device.
 138
 139     @param[in]  fd    File Descriptor for the file or device to write.
 140     @param[in]  buf   Buffer to write data from.
 141     @param[in]  N     Maximum number of bytes to write.
 142
 143     @return   On successful completion, write returns a non-negative integer
 144               indicating the number of bytes actually written.  Otherwise, it
 145               returns -1 and sets errno as follows:
 146                 - EAGAIN
 147                 - EWOULDBLOCK
 148                 - EBADF
 149                 - EFBIG
 150                 - EINTR
 151                 - EINVAL
 152                 - EIO
 153                 - ENOSPC
 154                 - EPIPE
 155                 - ERANGE
 156                 - ECONNRESET
 157                 - ENOBUFS
 158                 - ENXIO
 159                 - ENETDOWN
 160                 - ENETUNREACH
 161   **/
 162   ssize_t   write     (int fd, const void *buf, size_t n);
 163
 164   /** Unlink (delete) a file.
 165
 166     @param[in]  name    The name of the file to be deleted.
 167
 168     @retval   0   Successful completion.
 169     @retval  -1   Unable to perform operation, errno contains further
 170                   information.  The file name is unchanged.
 171   **/
 172   int       unlink    (const char *name);
 173
 174   /** Make file descriptor Fd2 a duplicate of file descriptor Fd1.
 175
 176     @param[in]  Fd1   File descriptor to be duplicated
 177     @param[in]  Fd2   File descriptor to become a duplicate of Fd1.
 178
 179     @retval   0   Successful completion.
 180     @retval  -1   Unable to perform operation, errno contains further
 181                   information.
 182   **/
 183   int       dup2      (int Fd1, int Fd2);
 184
 185   /** Remove a directory.
 186
 187     @param[in]  Path    Path to the directory to be deleted.
 188
 189     @retval   0   Successful completion.
 190     @retval  -1   Unable to perform operation, errno contains further
 191                   information.  The named directory remains unchanged.
 192   **/
 193   int       rmdir     (const char *Path);
 194
 195   /** Determine if fd refers to an interactive terminal device.
 196
 197     @param[in]  fd    The file descriptor to be tested.
 198
 199     @retval   0   The file descriptor, fd, is not for a terminal.  errno is set
 200                   indicating the cause for failure.
 201                     - EBADF   fd is not a valid open file descriptor.
 202                     - ENOTTY  fd does not refer to a terminal.
 203     @retval   1   The file descriptor, fd, is for a terminal.
 204   **/
 205   int       isatty    (int fd);
 206
 207 /* These system calls are also declared in sys/fcntl.h */
 208 #ifndef __FCNTL_SYSCALLS_DECLARED
 209   #define __FCNTL_SYSCALLS_DECLARED
 210
 211   /** Open or create a file named by name.
 212
 213       The file name may be one of:
 214         - An absolute path beginning with '/'.
 215         - A relative path beginning with "." or ".." or a directory name
 216         - A file name
 217         - A mapped path which begins with a name followed by a colon, ':'.
 218
 219       Mapped paths are use to refer to specific mass storage volumes or devices.
 220       In a Shell-hosted environment, the map command will list valid map names
 221       for both file system and block devices.  Mapped paths can also refer to
 222       devices such as the UEFI console.  Supported UEFI console mapped paths are:
 223         - stdin:        Standard Input        (from the System Table)
 224         - stdout:       Standard Output       (from the System Table)
 225         - stderr:       Standard Error Output (from the System Table)
 226
 227     @param[in]  name      Name of file to open.
 228     @param[in]  oflags    Flags as defined in fcntl.h.
 229     @param[in]  mode      Access mode to use if creating the file.
 230
 231     @return   Returns -1 on failure, otherwise the file descriptor for the open file.
 232   **/
 233   int     open      (const char *name, int oflags, int mode);
 234
 235   /** Create a new file or rewrite an existing one.
 236
 237       The creat() function behaves as if it is implemented as follows:
 238
 239         int creat(const char *path, mode_t mode)
 240         {
 241             return open(path, O_WRONLY|O_CREAT|O_TRUNC, mode);
 242         }
 243
 244     @param[in]    Path    The name of the file to create.
 245     @param[in]    Mode    Access mode (permissions) for the new file.
 246
 247     @return   Returns -1 on failure, otherwise the file descriptor for the open file.
 248   **/
 249   int     creat     (const char *Path, mode_t Mode);
 250
 251   /** File control
 252
 253       This function performs the operations described below and defined in <fcntl.h>.
 254
 255         - F_DUPFD: Return the lowest numbered file descriptor available that is >= the third argument.
 256                    The new file descriptor refers to the same open file as Fd.
 257
 258         - F_SETFD: Set the file descriptor flags to the value specified by the third argument.
 259         - F_GETFD: Get the file descriptor flags associated with Fd.
 260         - F_SETFL: Set the file status flags based upon the value of the third argument.
 261         - F_GETFL: Get the file status flags and access modes for file Fd.
 262
 263     @param[in]  Fd      File descriptor associated with the file to be controlled.
 264     @param[in]  Cmd     Command to execute.
 265     @param[in]  ...     Additional arguments, as needed by Cmd.
 266
 267     @return   A -1 is returned to indicate failure, otherwise the value
 268               returned is positive and depends upon Cmd as follows:
 269                 - F_DUPFD: A new file descriptor.
 270                 - F_SETFD: files previous file descriptor flags.
 271                 - F_GETFD: The files file descriptor flags.
 272                 - F_SETFL: The old status flags and access mode of the file.
 273                 - F_GETFL: The status flags and access mode of the file.
 274   **/
 275   int     fcntl     (int Fd, int Cmd, ...);
 276 #endif  // __FCNTL_SYSCALLS_DECLARED
 277
 278 /* These system calls are also declared in stat.h */
 279 #ifndef __STAT_SYSCALLS_DECLARED
 280   #define __STAT_SYSCALLS_DECLARED
 281
 282   int     mkdir     (const char *, mode_t);
 283   int     fstat     (int, struct stat *);
 284   int     lstat     (const char *, struct stat *);
 285   int     stat      (const char *, struct stat *);
 286   int     chmod     (const char *, mode_t);
 287   mode_t  umask     (mode_t cmask);
 288
 289 #endif  // __STAT_SYSCALLS_DECLARED
 290
 291 // These are also declared in sys/types.h
 292 #ifndef __OFF_T_SYSCALLS_DECLARED
 293   #define __OFF_T_SYSCALLS_DECLARED
 294   off_t   lseek     (int, off_t, int);
 295   int     truncate  (const char *, off_t);
 296   int     ftruncate (int, off_t);   //  IEEE Std 1003.1b-93
 297 #endif /* __OFF_T_SYSCALLS_DECLARED */
 298
 299 /* EFI-specific Functions. */
 300
 301   /** Mark an open file to be deleted when it is closed.
 302
 303     @param[in]  fd    File descriptor for the open file.
 304
 305     @retval   0   The flag was set successfully.
 306     @retval  -1   An invalid fd was specified.
 307   **/
 308   int       DeleteOnClose(int fd);
 309
 310   /** Find and reserve a free File Descriptor.
 311
 312   Returns the first free File Descriptor greater than or equal to the,
 313   already validated, fd specified by Minfd.
 314
 315   @return   Returns -1 if there are no free FDs.  Otherwise returns the
 316             found fd.
 317   */
 318   int       FindFreeFD  (int MinFd);
 319
 320   /** Validate that fd refers to a valid file descriptor.
 321     IsOpen is interpreted as follows:
 322       - Positive  fd must be OPEN
 323       - Zero      fd must be CLOSED
 324       - Negative  fd may be OPEN or CLOSED
 325
 326     @retval TRUE  fd is VALID
 327     @retval FALSE fd is INVALID
 328   */
 329   BOOLEAN   ValidateFD (int fd, int IsOpen);
 330
 331
 332 /* These system calls don't YET have EFI implementations. */
 333   int       reboot    (int, char *);
 334 __END_DECLS
 335
 336 #endif  /* _EFI_SYS_CALL_H */