## GskStreamFd

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);
    gboolean            gsk_stream_fd_duplex_pipe           (GskStream **side_a_out,
                                                             GskStream **side_b_out,
                                                             GError **error);
    gboolean            gsk_stream_fd_duplex_pipe_fd        (GskStream **side_a_out,
                                                             int *side_b_fd_out,
                                                             GError **error);
    GskStream *         gsk_stream_fd_new_from_symbolic_address
                                                            (GskSocketAddressSymbolic *symbolic,
                                                             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)

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

Try to guess the nature of the file-descriptor using `fstat()`, `isatty()`.

`fd` : | the file-descriptor to use as the basis for a stream.
Returns : | a new GskStream which will free `fd` when it is closed.

### 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

### gsk_stream_fd_duplex_pipe ()

    gboolean            gsk_stream_fd_duplex_pipe           (GskStream **side_a_out,
                                                             GskStream **side_b_out,
                                                             GError **error);

Create a pair of file-descriptors that are connected to eachother, and make GskStreamFds around them.

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

### gsk_stream_fd_duplex_pipe_fd ()

    gboolean            gsk_stream_fd_duplex_pipe_fd        (GskStream **side_a_out,
                                                             int *side_b_fd_out,
                                                             GError **error);

Create a pair of file-descriptors that are connected to eachother, and make a GskStreamFd around one of them.

`side_a_out` : | place to store a reference to a newly allocated stream-fd.
`side_b_fd_out` : | place to store a new file-descriptor.
`error` : | optional error return value.
Returns : | whether the file-descriptors were allocated successfully.

### gsk_stream_fd_new_from_symbolic_address ()

    GskStream *         gsk_stream_fd_new_from_symbolic_address
                                                            (GskSocketAddressSymbolic *symbolic,
                                                             GError **error);

Create a stream connecting to a symbolic socket-address.

`symbolic` : | a symbolic address. name resolution will begin immediately.
`error` : | optional error return value.
Returns : | a new GskStream

## Property Details

### 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