root/opal/util/fd.h

INCLUDED FROM

   1 /*
   2  * Copyright (c) 2008-2018 Cisco Systems, Inc.  All rights reserved
   3  * Copyright (c) 2009 Sandia National Laboratories. All rights reserved.
   4  * Copyright (c) 2017      Mellanox Technologies. All rights reserved.
   5  *
   6  * $COPYRIGHT$
   7  *
   8  * Additional copyrights may follow
   9  *
  10  * $HEADER$
  11  */
  12 
  13 /* @file */
  14 
  15 #ifndef OPAL_UTIL_FD_H_
  16 #define OPAL_UTIL_FD_H_
  17 
  18 #include "opal_config.h"
  19 
  20 BEGIN_C_DECLS
  21 
  22 /**
  23  * Read a complete buffer from a file descriptor.
  24  *
  25  * @param fd File descriptor
  26  * @param len Number of bytes to read
  27  * @param buffer Pre-allocated buffer (large enough to hold len bytes)
  28  *
  29  * @returns OPAL_SUCCESS upon success.
  30  * @returns OPAL_ERR_TIMEOUT if the fd closes before reading the full amount.
  31  * @returns OPAL_ERR_IN_ERRNO otherwise.
  32  *
  33  * Loop over reading from the fd until len bytes are read or an error
  34  * occurs.  EAGAIN and EINTR are transparently handled.
  35  */
  36 OPAL_DECLSPEC int opal_fd_read(int fd, int len, void *buffer);
  37 
  38 /**
  39  * Write a complete buffer to a file descriptor.
  40  *
  41  * @param fd File descriptor
  42  * @param len Number of bytes to write
  43  * @param buffer Buffer to write from
  44  *
  45  * @returns OPAL_SUCCESS upon success.
  46  * @returns OPAL_ERR_IN_ERRNO otherwise.
  47  *
  48  * Loop over writing to the fd until len bytes are written or an error
  49  * occurs.  EAGAIN and EINTR are transparently handled.
  50  */
  51 OPAL_DECLSPEC int opal_fd_write(int fd, int len, const void *buffer);
  52 
  53 /**
  54  * Convenience function to set a file descriptor to be close-on-exec.
  55  *
  56  * @param fd File descriptor
  57  *
  58  * @returns OPAL_SUCCESS upon success (or if the system does not
  59  * support close-on-exec behavior).
  60  * @returns OPAL_ERR_IN_ERRNO otherwise.
  61  *
  62  * This is simply a convenience function because there's a few steps
  63  * to setting a file descriptor to be close-on-exec.
  64  */
  65 OPAL_DECLSPEC int opal_fd_set_cloexec(int fd);
  66 
  67 /**
  68  * Convenience function to check if fd point to an accessible regular file.
  69  *
  70  * @param fd File descriptor
  71  *
  72  * @returns true if "fd" points to a regular file.
  73  * @returns false otherwise.
  74  */
  75 OPAL_DECLSPEC bool opal_fd_is_regular(int fd);
  76 
  77 /**
  78  * Convenience function to check if fd point to an accessible character device.
  79  *
  80  * @param fd File descriptor
  81  *
  82  * @returns true if "fd" points to a regular file.
  83  * @returns false otherwise.
  84  */
  85 OPAL_DECLSPEC bool opal_fd_is_chardev(int fd);
  86 
  87 /**
  88  * Convenience function to check if fd point to an accessible block device.
  89  *
  90  * @param fd File descriptor
  91  *
  92  * @returns true if "fd" points to a regular file.
  93  * @returns false otherwise.
  94  */
  95 OPAL_DECLSPEC bool opal_fd_is_blkdev(int fd);
  96 
  97 /**
  98  * Convenience function to get a string name of the peer on the other
  99  * end of this internet socket.
 100  *
 101  * @param fd File descriptor of an AF_INET/AF_INET6 socket
 102  *
 103  * @returns resolvable IP name, or "a.b.c.d".  This string must be freed by the caller.
 104  */
 105 OPAL_DECLSPEC const char *opal_fd_get_peer_name(int fd);
 106 
 107 END_C_DECLS
 108 
 109 #endif