pluginIO(bpContext ctx, struct io_pkt io)

Called to do the input (backup) or output (restore) of data from or to a file for a command plugin. These routines simulate the Unix read(), write(), open(), close(), and lseek() I/O calls, and the arguments are passed in the packet and the return values are also placed in the packet. In addition for Win32 systems the plugin must return two additional values (described below).

enum {
  IO_OPEN = 1,
  IO_READ = 2,
  IO_WRITE = 3,
  IO_CLOSE = 4,
  IO_SEEK = 5
};

struct io_pkt {
  int32_t pkt_size;                  /* Size of this packet */
  int32_t func;                      /* Function code */
  int32_t count;                     /* read/write count */
  mode_t mode;                       /* permissions for created files */
  int32_t flags;                     /* Open flags */
  char *buf;                         /* read/write buffer */
  const char *fname;                 /* open filename */
  int32_t status;                    /* return status */
  int32_t io_errno;                  /* errno code */
  int32_t lerror;                    /* Win32 error code */
  int32_t whence;                    /* lseek argument */
  boffset_t offset;                  /* lseek argument */
  bool win32;                        /* Win32 GetLastError returned */
  int32_t pkt_end;                   /* end packet sentinel */
};

The particular Unix function being simulated is indicated by the func, which will have one of the IO_OPEN, IO_READ, … codes listed above. The status code that would be returned from a Unix call is returned in status for IO_OPEN, IO_CLOSE, IO_READ, and IO_WRITE. The return value for IO_SEEK is returned in offset which in general is a 64 bit value.

When there is an error on Unix systems, you must always set io_error, and on a Win32 system, you must always set win32, and the returned value from the OS call GetLastError() in lerror.

For all except IO_SEEK, status is the return result. In general it is a positive integer unless there is an error in which case it is -1.

The following describes each call and what you get and what you should return:

IO_OPEN

You will be passed fname, mode, and flags. You must set on return: status, and if there is a Unix error io_errno must be set to the errno value, and if there is a Win32 error win32 and lerror.

IO_READ

You will be passed: count, and buf (buffer of size count). You must set on return: status to the number of bytes read into the buffer (buf) or -1 on an error, and if there is a Unix error io_errno must be set to the errno value, and if there is a Win32 error, win32 and lerror must be set.

IO_WRITE

You will be passed: count, and buf (buffer of size count). You must set on return: status to the number of bytes written from the buffer (buf) or -1 on an error, and if there is a Unix error io_errno must be set to the errno value, and if there is a Win32 error, win32 and lerror must be set.

IO_CLOSE

Nothing will be passed to you. On return you must set status to 0 on success and -1 on failure. If there is a Unix error io_errno must be set to the errno value, and if there is a Win32 error, win32 and lerror must be set.

IO_LSEEK

You will be passed: offset, and whence. offset is a 64 bit value and is the position to seek to relative to whence. whence is one of the following SEEK_SET, SEEK_CUR, or SEEK_END indicating to either to seek to an absolute possition, relative to the current position or relative to the end of the file. You must pass back in offset the absolute location to which you seeked. If there is an error, offset should be set to -1. If there is a Unix error io_errno must be set to the errno value, and if there is a Win32 error, win32 and lerror must be set.

Note: Bacula will call IO_SEEK only when writing a sparse file.

Possible Next Steps

Go back to Plugin EntryPoints.

Go back to Bacula FD Plugin API.

Go back to Developer Guide.

pluginIO(bpContext *ctx, struct io_pkt *io)

Possible Next Steps

pluginIO(bpContext ctx, struct io_pkt io)