+
+During each of the above calls, the plugin receives either no specific value or
+only one value, which in some cases may not be sufficient. However, knowing
+the context of the event, the plugin can call back to the Bacula entry points
+it was passed during the {\bf loadPlugin} call and get to a number of Bacula
+variables. (at the current time few Bacula variables are implemented, but it
+easily extended at a future time and as needs require).
+
+\subsection{startBackupFile(bpContext *ctx, struct save\_pkt *sp)}
+This entry point is called only if your plugin is a command plugin, and
+it is called when Bacula encounters the "Plugin = " directive in
+the Include section of the FileSet.
+Called when beginning the backup of a file. Here Bacula provides you
+with a pointer to the {\bf save\_pkt} structure and you must fill in
+this packet with the "attribute" data of the file.
+
+\begin{verbatim}
+struct save_pkt {
+ int32_t pkt_size; /* size of this packet */
+ char *fname; /* Full path and filename */
+ char *link; /* Link name if any */
+ struct stat statp; /* System stat() packet for file */
+ int32_t type; /* FT_xx for this file */
+ uint32_t flags; /* Bacula internal flags */
+ bool portable; /* set if data format is portable */
+ char *cmd; /* command */
+ int32_t pkt_end; /* end packet sentinel */
+};
+\end{verbatim}
+
+The second argument is a pointer to the {\bf save\_pkt} structure for the file
+to be backed up. The plugin is responsible for filling in all the fields
+of the {\bf save\_pkt}. If you are backing up
+a real file, then generally, the statp structure can be filled in by doing
+a {\bf stat} system call on the file.
+
+If you are backing up a database or
+something that is more complex, you might want to create a virtual file.
+That is a file that does not actually exist on the filesystem, but represents
+say an object that you are backing up. In that case, you need to ensure
+that the {\bf fname} string that you pass back is unique so that it
+does not conflict with a real file on the system, and you need to
+artifically create values in the statp packet.
+
+Example programs such as {\bf bpipe-fd.c} show how to set these fields. You
+must take care not to store pointers the stack in the pointer fields such as
+fname and link, because when you return from your function, your stack entries
+will be destroyed. The solution in that case is to malloc() and return the
+pointer to it. In order to not have memory leaks, you should store a pointer to
+all memory allocated in your pContext structure so that in subsequent calls or
+at termination, you can release it back to the system.
+
+Once the backup has begun, Bacula will call your plugin at the {\bf pluginIO}
+entry point to "read" the data to be backed up. Please see the {\bf bpipe-fd.c}
+plugin for how to do I/O.
+
+Example of filling in the save\_pkt as used in bpipe-fd.c:
+
+\begin{verbatim}
+ struct plugin_ctx *p_ctx = (struct plugin_ctx *)ctx->pContext;
+ time_t now = time(NULL);
+ sp->fname = p_ctx->fname;
+ sp->statp.st_mode = 0700 | S_IFREG;
+ sp->statp.st_ctime = now;
+ sp->statp.st_mtime = now;
+ sp->statp.st_atime = now;
+ sp->statp.st_size = -1;
+ sp->statp.st_blksize = 4096;
+ sp->statp.st_blocks = 1;
+ p_ctx->backup = true;
+ return bRC_OK;
+\end{verbatim}
+
+Note: the filename to be created has already been created from the
+command string previously sent to the plugin and is in the plugin
+context (p\_ctx->fname) and is a malloc()ed string. This example
+creates a regular file (S\_IFREG), with various fields being created.
+
+In general, the sequence of commands issued from Bacula to the plugin
+to do a backup while processing the "Plugin = " directive are:
+
+\begin{enumerate}
+ \item generate a bEventBackupCommand event to the specified plugin
+ and pass it the command string.
+ \item make a startPluginBackup call to the plugin, which
+ fills in the data needed in save\_pkt to save as the file
+ attributes and to put on the Volume and in the catalog.
+ \item call Bacula's internal save\_file() subroutine to save the specified
+ file. The plugin will then be called at pluginIO() to "open"
+ the file, and then to read the file data.
+ Note, if you are dealing with a virtual file, the "open" operation
+ is something the plugin does internally and it doesn't necessarily
+ mean opening a file on the filesystem. For example in the case of
+ the bpipe-fd.c program, it initiates a pipe to the requested program.
+ Finally when the plugin signals to Bacula that all the data was read,
+ Bacula will call the plugin with the "close" pluginIO() function.
+\end{enumerate}
+
+
+\subsection{endBackupFile(bpContext *ctx)}
+Called at the end of backing up a file for a command plugin. If the plugin's
+work is done, it should return bRC\_OK. If the plugin wishes to create another
+file and back it up, then it must return bRC\_More (not yet implemented). This
+is probably a good time to release any malloc()ed memory you used to pass back
+filenames.
+
+\subsection{startRestoreFile(bpContext *ctx, const char *cmd)}
+Called when the first record is read from the Volume that was
+previously written by the command plugin.
+
+\subsection{createFile(bpContext *ctx, struct restore\_pkt *rp)}
+Called for a command plugin to create a file during a Restore job before
+restoring the data.
+This entry point is called before any I/O is done on the file. After
+this call, Bacula will call pluginIO() to open the file for write.
+
+The data in the
+restore\_pkt is passed to the plugin and is based on the data that was
+originally given by the plugin during the backup and the current user
+restore settings (e.g. where, RegexWhere, replace). This allows the
+plugin to first create a file (if necessary) so that the data can
+be transmitted to it. The next call to the plugin will be a
+pluginIO command with a request to open the file write-only.
+
+This call must return one of the following values:
+
+\begin{verbatim}
+ enum {
+ CF_SKIP = 1, /* skip file (not newer or something) */
+ CF_ERROR, /* error creating file */
+ CF_EXTRACT, /* file created, data to extract */
+ CF_CREATED /* file created, no data to extract */
+};
+\end{verbatim}
+
+in the restore\_pkt value {\bf create\_status}. For a normal file,
+unless there is an error, you must return {\bf CF\_EXTRACT}.
+
+\begin{verbatim}
+
+struct restore_pkt {
+ int32_t pkt_size; /* size of this packet */
+ int32_t stream; /* attribute stream id */
+ int32_t data_stream; /* id of data stream to follow */
+ int32_t type; /* file type FT */
+ int32_t file_index; /* file index */
+ int32_t LinkFI; /* file index to data if hard link */
+ uid_t uid; /* userid */
+ struct stat statp; /* decoded stat packet */
+ const char *attrEx; /* extended attributes if any */
+ const char *ofname; /* output filename */
+ const char *olname; /* output link name */
+ const char *where; /* where */
+ const char *RegexWhere; /* regex where */
+ int replace; /* replace flag */
+ int create_status; /* status from createFile() */
+ int32_t pkt_end; /* end packet sentinel */
+
+};
+\end{verbatim}
+
+Typical code to create a regular file would be the following:
+
+\begin{verbatim}
+ struct plugin_ctx *p_ctx = (struct plugin_ctx *)ctx->pContext;
+ time_t now = time(NULL);
+ sp->fname = p_ctx->fname; /* set the full path/filename I want to create */
+ sp->type = FT_REG;
+ sp->statp.st_mode = 0700 | S_IFREG;
+ sp->statp.st_ctime = now;
+ sp->statp.st_mtime = now;
+ sp->statp.st_atime = now;
+ sp->statp.st_size = -1;
+ sp->statp.st_blksize = 4096;
+ sp->statp.st_blocks = 1;
+ return bRC_OK;
+\end{verbatim}
+
+This will create a virtual file. If you are creating a file that actually
+exists, you will most likely want to fill the statp packet using the
+stat() system call.
+
+Creating a directory is similar, but requires a few extra steps:
+
+\begin{verbatim}
+ struct plugin_ctx *p_ctx = (struct plugin_ctx *)ctx->pContext;
+ time_t now = time(NULL);
+ sp->fname = p_ctx->fname; /* set the full path I want to create */
+ sp->link = xxx; where xxx is p_ctx->fname with a trailing forward slash
+ sp->type = FT_DIREND
+ sp->statp.st_mode = 0700 | S_IFDIR;
+ sp->statp.st_ctime = now;
+ sp->statp.st_mtime = now;
+ sp->statp.st_atime = now;
+ sp->statp.st_size = -1;
+ sp->statp.st_blksize = 4096;
+ sp->statp.st_blocks = 1;
+ return bRC_OK;
+\end{verbatim}
+
+The link field must be set with the full cononical path name, which always
+ends with a forward slash. If you do not terminate it with a forward slash,
+you will surely have problems later.
+
+As with the example that creates a file, if you are backing up a real
+directory, you will want to do an stat() on the directory.
+
+Note, if you want the directory permissions and times to be correctly
+restored, you must create the directory {\bf after} all the file directories
+have been sent to Bacula. That allows the restore process to restore all the
+files in a directory using default directory options, then at the end, restore
+the directory permissions. If you do it the other way around, each time you
+restore a file, the OS will modify the time values for the directory entry.
+
+\subsection{setFileAttributes(bpContext *ctx, struct restore\_pkt *rp)}
+This is call not yet implemented. Called for a command plugin.
+
+See the definition of {\bf restre\_pkt} in the above section.
+
+\subsection{endRestoreFile(bpContext *ctx)}
+Called when a command plugin is done restoring a file.
+
+\subsection{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).
+
+\begin{verbatim}
+ 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 */
+};
+\end{verbatim}
+
+The particular Unix function being simulated is indicated by the {\bf 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 {\bf status}
+for IO\_OPEN, IO\_CLOSE, IO\_READ, and IO\_WRITE. The return value for IO\_SEEK
+is returned in {\bf 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, {\bf 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:
+
+\begin{description}
+ \item [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.
+
+ \item [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.
+
+ \item [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.
+
+ \item [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.
+
+ \item [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.
+
+\end{description}
+
+\section{Bacula Plugin Entrypoints}
+When Bacula calls one of your plugin entrypoints, you can call back to
+the entrypoints in Bacula that were supplied during the xxx plugin call
+to get or set information within Bacula.
+
+\subsection{bRC registerBaculaEvents(bpContext *ctx, ...)}
+This Bacula entrypoint will allow you to register to receive events
+that are not autmatically passed to your plugin by default. This
+entrypoint currently is unimplemented.
+
+\subsection{bRC getBaculaValue(bpContext *ctx, bVariable var, void *value)}
+Calling this entrypoint, you can obtain specific values that are available
+in Bacula.
+
+\subsection{bRC setBaculaValue(bpContext *ctx, bVariable var, void *value)}
+Calling this entrypoint allows you to set particular values in
+Bacula.
+
+\subsection{bRC JobMessage(bpContext *ctx, const char *file, int line,
+ int type, time\_t mtime, const char *fmt, ...)}
+This call permits you to put a message in the Job Report.
+
+
+\subsection{bRC DebugMessage(bpContext *ctx, const char *file, int line,
+ int level, const char *fmt, ...)}
+This call permits you to print a debug message.
+
+
+\subsection{void baculaMalloc(bpContext *ctx, const char *file, int line,
+ size\_t size)}
+This call permits you to obtain memory from Bacula's memory allocator.
+
+
+\subsection{void baculaFree(bpContext *ctx, const char *file, int line, void *mem)}
+This call permits you to free memory obtained from Bacula's memory allocator.