send_file, Subroutine

Online bearbeiten

Zweck

Sendet den Inhalt einer Datei über einen Socket.

Bibliothek

Standard-C-Bibliothek (libc.a)

Syntax

#include < sys/socket.h >

ssize_t send_file(Socket_p, sf_iobuf, flags)

int * Socket_p;
struct sf_parms * sf_iobuf;
uint_t  flags;

Beschreibung

Die Subroutine Sendedatei sendet Daten aus der geöffneten Datei, die im Parameter Sf_iobuf angegeben ist, über das verbundene Socket, auf das der Parameter Socket-p verweist.

Anmerkung: Derzeit unterstützt der Sendedatei nur das TCP/IP-Protokoll (Socket SOCK_STREAM in AF_INET). Wenn diese Funktion für alle anderen Sockettypen verwendet wird, wird ein Fehler zurückgegeben.

Parameter

Element Beschreibung
Socket-p Verweist auf den Socketdeskriptor des Sockets, an den die Datei gesendet wird.
Anmerkung: Dies unterscheidet sich von den meisten Socketfunktionen.
Sf_iobuf Verweist auf eine wie folgt definierte sf_parameter -Struktur:
/*
 * Structure for the send_file system call
 */
#ifdef __64BIT__
#define SF_INT64(x)     int64_t x;
#define SF_UINT64(x)    uint64_t x;
#else
#ifdef _LONG_LONG
#define SF_INT64(x)     int64_t x;
#define SF_UINT64(x)    uint64_t x;
#else
#define SF_INT64(x)     int filler_##x; int x;
#define SF_UINT64(x)    int filler_##x; uint_t x;
#endif
#endif

struct sf_parms {
    /* --------- header parms ---------- */
    void      *header_data;         /* Input/Output. Points to header buf */
    uint_t      header_length;      /* Input/Output. Length of the header */
    /* --------- file parms ------------ */
    int       file_descriptor;      /* Input. File descriptor of the file */
    SF_UINT64(file_size)            /* Output. Size of the file */
    SF_UINT64(file_offset)          /* Input/Output. Starting offset */
    SF_INT64(file_bytes)            /* Input/Output. number of bytes to send */
    /* --------- trailer parms --------- */
   void      *trailer_data;         /* Input/Output. Points to trailer buf */
   uint_t    trailer_length;        /* Input/Output. Length of the trailer */
    /* --------- return info ----------- */
    SF_UINT64(bytes_sent)           /* Output. number of bytes sent */
};
Headerdaten
Verweist auf einen Puffer, der Headerdaten enthält, die vor den Dateidaten gesendet werden sollen Kann ein Nullzeiger sein, wenn Headerlänge 0 ist. Dieses Feld wird von Sendedatei aktualisiert, wenn der Header übertragen wird, d. h.header_data+ Anzahl der Bytes des gesendeten Headers.
Headerlänge
Gibt die Anzahl der Byte in Headerdatenan. Dieses Feld muss auf 0 gesetzt werden, um anzugeben, dass keine Headerdaten gesendet werden sollen. Dieses Feld wird von Sendedatei aktualisiert, wenn der Header übertragen wird, d. h.header_length-Anzahl der Bytes des gesendeten Headers.
Dateideskriptor
Gibt den Dateideskriptor für eine Datei an, die geöffnet und lesbar ist. Dies ist der Deskriptor für die Datei, die die zu übertragenden Daten enthält. Die Dateideskriptor wird ignoriert, wenn Dateibyte = 0. Dieses Feld wird von Sendedateinicht aktualisiert.
Dateigröße
Enthält die Bytegröße der Datei, die durch Dateideskriptorangegeben wird Dieses Feld wird vom Kernel ausgefüllt.
Dateioffset
Gibt die relative Byteadresse in der Datei an, ab der Daten gesendet werden sollen. Dieses Feld wird von Sendedatei aktualisiert, wenn Dateidaten übertragen werden, d. h.file_offset+ Anzahl Byte der gesendeten Dateidaten.
Dateibyte
Gibt die Anzahl Byte aus der zu übertragenden Datei an. Wird file_bytes auf -1 gesetzt, wird die gesamte Datei ab file_offset übertragen. Wenn dieses Feld nicht auf -1 gesetzt ist, wird es von send_file aktualisiert, wenn Dateidaten übertragen werden - das heißt,file_bytes-Anzahl der Byte der gesendeten Dateidaten.
Trailer_Data
Verweist auf einen Puffer, der Trailerdaten enthält, die nach den Dateidaten gesendet werden sollen Kann ein Nullzeiger sein, wenn Trailer_Länge 0 ist. Dieses Feld wird von Sendedatei aktualisiert, wenn der Trailer übertragen wird, d. h.trailer_data+ Anzahl der Bytes des gesendeten Trailers.
Trailer_Länge
Gibt die Anzahl der Byte in Trailer_Dataan. Dieses Feld muss auf 0 gesetzt werden, um anzugeben, dass keine Abschlussdaten gesendet werden. Dieses Feld wird von Sendedatei aktualisiert, wenn der Trailer übertragen wird, d. h.trailer_length-Anzahl der Byte des gesendeten Trailers.
gesendete Byte
Enthält die Anzahl der Byte, die in diesem Aufruf an Sendedateitatsächlich gesendet wurden Dieses Feld wird vom Kernel ausgefüllt.

Alle Felder markiert mitInputin der sf_parameter -Struktur erfordert die Einrichtung durch eine Anwendung vor den Sendedatei -Aufrufen. Alle Felder markiert mitOutputin der sf_parameter -Struktur wird von Sendedatei angepasst, wenn die Daten erfolgreich übertragen wurden, d. h., die angegebene Datenübertragung teilweise oder vollständig erfolgt ist.

Die Subroutine Sendedatei versucht, Headerlänge Byte aus dem Puffer, auf den Headerdatenverweist, gefolgt von Dateibyte aus der Datei, die Dateideskriptorzugeordnet ist, gefolgt von Trailer_Länge Byte aus dem Puffer, auf den Trailer_Dataverweist, über die Verbindung zu schreiben, die dem Socket zugeordnet ist, auf den Socket-pverweist.

Beim Senden der Daten aktualisiert der Kernel die Parameter, auf die von Sf_iobuf verwiesen wird, sodass die Anwendung den Befehl Sendedatei erneut ausgeben kann, ohne die Parameter immer wieder neu festzulegen oder anzupassen, wenn die Sendedatei mehrmals aufgerufen werden muss (entweder aufgrund von Signalunterbrechungen oder aufgrund des nicht blockierenden E/A-Modus), um eine Dateidatenübertragung abzuschließen.

Wenn die Anwendung file_offset größer als die tatsächliche Dateigröße oder file_bytes größer als (tatsächliche Dateigröße - file_offset) setzt, ist der Rückgabewert -1 mit errno EINVAL.
Flags Gibt die folgenden Attribute an:
SF_SCHLIE
Schließt den Socket, auf den Socket-p verweist, nachdem die Daten erfolgreich gesendet oder zur Übertragung in die Warteschlange gestellt wurden.
SF_REUSE (VERWENDEN)
Bereitet den Socket für die Wiederverwendung vor, nachdem die Daten erfolgreich gesendet oder zur Übertragung in die Warteschlange gestellt wurden und die vorhandene Verbindung geschlossen wurde.
Anmerkung: Diese Option wird derzeit unter diesem Betriebssystem nicht unterstützt.
SF_NICHT_CACHEN
Stellt die angegebene Datei nicht in den Netzpuffercache.
SF_SYNC_CACHE
Überprüft/aktualisiert den Netzpuffercache für die angegebene Datei vor der Übertragung.

Wenn das Flag SF_SCHLIE gesetzt ist, wird das durch Socket-p angegebene verbundene Socket von Sendedatei getrennt und geschlossen, nachdem die angeforderte Übertragung erfolgreich ausgeführt wurde. Der Socket-Deskriptor, auf den Socket_p verweist, wird auf -1 gesetzt. Dieses Flag wird nicht wirksam, wenn send_file einen Wert non-0 zurückgibt.

Das Flag SF_REUSE wird derzeit von AIX® nicht unterstützt. Wenn dieses Flag angegeben ist, wird der Socket, auf den Socket_p zeigt, geschlossen und als -1 zurückgegeben. Für die nächste Verbindung muss ein neuer Socket erstellt werden.

Sendedatei nutzt einen Netzpuffercache im Kernelspeicher, um die Ausgabedateidaten dynamisch zwischenzuspeichern. Dies trägt zur Verbesserung der Sendedatei -Leistung für folgende Dateien bei:

  1. wiederholt über das Netzwerk und
  2. nicht häufig geändert.

Anwendungen können die angegebene Datei mit dem Flag SF_DONT_CACHE aus dem Cache ausschließen. Sendedatei aktualisiert den Cache häufig, um sicherzustellen, dass die Dateidaten im Cache für einen bestimmten Zeitraum gültig sind. Der Netzoptionsparameter "send_file_duration", der vom Befehl Nein gesteuert wird, kann geändert werden, um das Intervall der Sendedatei -Cacheprüfung zu konfigurieren. Der Standardwert ist 300 (in Sekunden). Anwendungen können das Flag SF_SYNC_CACHE verwenden, um sicherzustellen, dass eine Cacheprüfung der angegebenen Datei erfolgt, bevor die Datei von Sendedateigesendet wird, unabhängig vom Wert von "send_file_duration". Weitere Parameter für den Netzpuffercache sind "nbc_limit", nbc_max_cache "und nbc_min_cache". Weitere Informationen finden Sie in der Beschreibung des Befehls Nein .

Rückgabewert

Es gibt drei mögliche Rückgabewerte von Sendedatei:

Wert Beschreibung
-1 Es ist ein Fehler aufgetreten. errno enthält den Fehlercode.
0 Der Befehl wurde erfolgreich ausgeführt.
1 Der Befehl wurde teilweise ausgeführt, einige Daten wurden übertragen, aber der Befehl muss aus irgendeinem Grund zurückkehren, z. B. wurde der Befehl durch Signale unterbrochen.

Felder markiert mitOutputIn der Struktur sf_parameter (auf die Sf_iobufverweist) wird von Sendedatei aktualisiert, wenn der Rückgabewert 0 oder 1 ist. Das Feld Gesendete Byte enthält die Gesamtzahl Byte, die in diesem Aufruf gesendet wurden. Es ist immer wahr, dass Gesendete Byte (Output) <= Headerlänge(Input) + Dateibyte(Input) + Trailer_Länge (Input).

Der Sendedatei unterstützt den blockierenden E/A-Modus und den nicht blockierenden E/A-Modus. Im blockierenden E/A-Modus blockiert Sendedatei , bis alle Dateidaten (einschließlich Header und Trailer) gesendet wurden. Sie passt die Sf_iobuf an, um die Übertragungsergebnisse wiederzugeben, und gibt 0 zurück. Es ist möglich, dass Sendedatei unterbrochen werden kann, bevor die Anforderung vollständig ausgeführt wurde. In diesem Fall passt es die Sf_iobuf an, um den Übertragungsfortschritt widerzuspiegeln, und gibt 1 zurück.

Im nicht blockierenden E/A-Modus überträgt Sendedatei so viel, wie der Socketspeicherbereich zulässt, passt die Sf_iobuf an den Übertragungsfortschritt an und gibt 0 oder 1 zurück. Wenn kein Socket-Speicherplatz im System vorhanden ist, um die Daten zu puffern, gibt send_file -1 zurück und setzt errno auf EWOULDBLOCK. Auswählen oder Umfrage kann verwendet werden, um festzustellen, wann es möglich ist, mehr Daten zu senden.

Mögliche zurückgegebene Fehlernummer:
EBADF Der Socket-oder Dateideskriptorparameter ist ungültig.
ENDEOSOCK Der Socketparameter verweist auf eine Datei, nicht auf einen Socket.
EPROTONOUNTERSTÜTZUNG Protokoll nicht unterstützt.
EFAULT Die im Parameter HeaderTailer angegebenen Adressen befinden sich nicht in einem beschreibbaren Teil des Benutzeradressraums.
EINTR Die Operation wurde durch ein Signal unterbrochen, bevor Daten gesendet wurden. (Wenn einige Daten gesendet wurden, gibt Sendedatei die Anzahl der Bytes zurück, die vor dem Signal gesendet wurden, und EINTR ist nicht festgelegt.)
EINVAL Der Parameter offset, length of the HeaderTrailer, oder flags ist ungültig.
ENOTCONN Ein Sendedatei an einem Socket, das nicht verbunden ist, ein Sendedatei an einem Socket, der die Verbindungssequenz nicht mit seinem Peer abgeschlossen hat oder nicht mehr mit seinem Peer verbunden ist
EWOULDBLOCK Der Socket wird als nicht blockierend markiert, und die angeforderte Operation würde blockiert.
ENOMEM Im System ist kein Speicher zum Ausführen der Operation verfügbar.

PerformanceNote

Durch die Nutzung des Netzpuffercache bietet Sendedatei eine bessere Leistung und einen besseren Netzdurchsatz für die Dateiübertragung. Es wird für Dateien, die größer als 4K Byte sind, empfohlen.