# GskStreamFd

## Name

GskStreamFd -- a file-descriptor based GskStream

## Synopsis

    #define     GSK_STREAM_FD_GET_FD            (stream)
                GskStreamFd;
    enum        GskStreamFdFlags;
    GskStream*  gsk_stream_fd_new               (gint fd,
                                                 GskStreamFdFlags flags);
    GskStream*  gsk_stream_fd_new_auto          (gint fd);
    GskStreamFdFlags gsk_stream_fd_flags_guess  (gint fd);
    gboolean    gsk_stream_fd_pipe              (GskStream **read_side_out,
                                                 GskStream **write_side_out,
                                                 GError **error);
    GskStream*  gsk_stream_fd_new_connecting    (gint fd);
    GskStream*  gsk_stream_fd_new_read_file     (const char *filename,
                                                 GError **error);
    GskStream*  gsk_stream_fd_new_write_file    (const char *filename,
                                                 gboolean may_create,
                                                 gboolean should_truncate,
                                                 GError **error);
    GskStream*  gsk_stream_fd_new_create_file   (const char *filename,
                                                 gboolean may_exist,
                                                 GError **error);
    GskStream*  gsk_stream_fd_new_open          (const char *filename,
                                                 guint open_flags,
                                                 guint permission,
                                                 GError **error);

## Object Hierarchy

      GObject
       +----GskIO
             +----GskStream
                   +----GskStreamFd

## Properties

      "file-descriptor"      GskFd                 : Read / Write / Construct Only
      "is-pollable"          gboolean              : Read / Write / Construct Only
      "is-readable"          gboolean              : Read / Write / Construct Only
      "is-writable"          gboolean              : Read / Write / Construct Only

## Description

a GskStream that can be used for files and sockets.

## Details

### GSK_STREAM_FD_GET_FD()

    #define GSK_STREAM_FD_GET_FD(stream)	(GSK_STREAM_FD (stream)->fd)

Get underlying file-descriptor from a GskStreamFd.

`stream` : | the stream.

### GskStreamFd

    typedef struct _GskStreamFd GskStreamFd;

An instance of a file-descriptor based stream.

### enum GskStreamFdFlags

    typedef enum
    {
      GSK_STREAM_FD_IS_READABLE     = (1<<0),
      GSK_STREAM_FD_IS_WRITABLE     = (1<<1),
      GSK_STREAM_FD_IS_READWRITE    = GSK_STREAM_FD_IS_READABLE
                                    | GSK_STREAM_FD_IS_WRITABLE,
      GSK_STREAM_FD_IS_POLLABLE     = (1<<2),
      GSK_STREAM_FD_IS_SHUTDOWNABLE = (1<<3),
      GSK_STREAM_FD_FOR_NEW_SOCKET  = GSK_STREAM_FD_IS_READWRITE
                                    | GSK_STREAM_FD_IS_POLLABLE
    			        | GSK_STREAM_FD_IS_SHUTDOWNABLE
    } GskStreamFdFlags;

### gsk_stream_fd_new ()

    GskStream*  gsk_stream_fd_new               (gint fd,
                                                 GskStreamFdFlags flags);

Create a new GskStream based on an already open file descriptor.

`fd` : | the raw file descriptor.
`flags` : | information about how to use the file descriptor.
Returns : | a new GskStream

### gsk_stream_fd_new_auto ()

    GskStream*  gsk_stream_fd_new_auto          (gint fd);

`fd` : |
Returns : |

### gsk_stream_fd_flags_guess ()

    GskStreamFdFlags gsk_stream_fd_flags_guess  (gint fd);

`fd` : |
Returns : |

### gsk_stream_fd_pipe ()

    gboolean    gsk_stream_fd_pipe              (GskStream **read_side_out,
                                                 GskStream **write_side_out,
                                                 GError **error);

Call the pipe(2) system call to make a half-duplex connection between two streams. The newly allocated streams are returned.

`read_side_out` : | place to store a reference to a newly allocated readable stream-fd.
`write_side_out` : | place to store a reference to a newly allocated writable stream-fd.
`error` : | optional error return value.
Returns : | whether the streams were allocated successfully.

### gsk_stream_fd_new_connecting ()

    GskStream*  gsk_stream_fd_new_connecting    (gint fd);

Create a new GskStream based on a socket which is still in the process of connecting.

`fd` : | the raw file descriptor.
Returns : | a new GskStream

### gsk_stream_fd_new_read_file ()

    GskStream*  gsk_stream_fd_new_read_file     (const char *filename,
                                                 GError **error);

Open a file for reading as a GskStream. The stream is not writable.

`filename` : | file to open readonly.
`error` : | optional error return value.
Returns : | a new GskStream

### gsk_stream_fd_new_write_file ()

    GskStream*  gsk_stream_fd_new_write_file    (const char *filename,
                                                 gboolean may_create,
                                                 gboolean should_truncate,
                                                 GError **error);

Open a file for writing as a GskStream. The stream is not readable.

`filename` : | file to open write-only.
`may_create` : | whether creating the filename is acceptable.
`should_truncate` : | whether an existing filename should be truncated.
`error` : | optional error return value.
Returns : | a new GskStream

### gsk_stream_fd_new_create_file ()

    GskStream*  gsk_stream_fd_new_create_file   (const char *filename,
                                                 gboolean may_exist,
                                                 GError **error);

Create a file for writing as a GskStream. The stream is not readable.

`filename` : | file to open write-only.
`may_exist` : | whether file may exist.
`error` : | optional error return value.
Returns : | a new GskStream

### gsk_stream_fd_new_open ()

    GskStream*  gsk_stream_fd_new_open          (const char *filename,
                                                 guint open_flags,
                                                 guint permission,
                                                 GError **error);

Open a file as a GskStream; this interface strongly reflects its underlying open(2) implementation. Using `gsk_stream_fd_new_read_file()` and `gsk_stream_fd_new_write_file()` may be more portable ultimately.

`filename` : | file to open or create (depending on `open_flags`)
`open_flags` : | same as the second argument to open(2).
`permission` : | permissions if creating a new file.
`error` : | optional error return value.
Returns : | a new GskStream

## Properties

### The "`file-descriptor`" property

      "file-descriptor"      GskFd                 : Read / Write / Construct Only

for reading and/or writing.

### The "`is-pollable`" property

      "is-pollable"          gboolean              : Read / Write / Construct Only

whether the file descriptor is pollable.

Default value: FALSE

### The "`is-readable`" property

      "is-readable"          gboolean              : Read / Write / Construct Only

is the FD readable.

Default value: FALSE

### The "`is-writable`" property

      "is-writable"          gboolean              : Read / Write / Construct Only

is the FD writable.

Default value: FALSE