Documentation PostgreSQL 8.0.25 | ||||
---|---|---|---|---|
Pr�c�dent | Arri�re rapide | Chapitre 28. Objets larges | Avance rapide | Suivant |
Cette section d�crit les possibilit�s que les biblioth�ques d'interfaces
client de PostgreSQL fournissent pour acc�der
aux objets larges. Toutes les manipulations d'objets larges utilisant ces
fonctions doivent prendre place dans un bloc de
transaction SQL. (Ce pr�requis est forc� strictement avec
PostgreSQL 6.5 bien que c'�tait un pr�requis implicite dans
les versions pr�c�dentes, ce qui a conduit � des mauvais comportements si
celui-ci �tait ignor�.) L'interface des objets larges de
PostgreSQL prend comme mod�le l'interface des
syst�mes de fichiers Unix avec des fonctions analogues
pour open
, read
,
write
,
lseek
, etc.
Les applications clients utilisant l'interface des objets larges dans libpq doivent inclure le fichier d'en-t�te libpq/libpq-fs.h et �tablir un lien avec la biblioth�que libpq.
La fonction
Oid lo_creat(PGconn *conn, int mode);
cr�e un nouvel objet large. mode est un masque d�crivant les diff�rents attributs du nouvel objet. Les constantes symboliques utilis�es ici sont d�finies dans le fichier d'en-t�te libpq/libpq-fs.h. Le type d'acc�s (lecture, �criture ou les deux) est contr�l� par une combinaison OU des bits INV_READ et INV_WRITE. Les 16 bits de poids faible du masque ont �t� utilis�s historiquement � Berkeley pour d�signer le num�ro du gestionnaire de stockage sur lequel l'objet large devrait r�sider. Ces bits devraient toujours �tre � z�ro maintenant. (Le type d'acc�s ne fait r�ellement rien de plus mais un ou deux des bits doivent �tre configur�s pour �viter une erreurs.) La valeur de retour est l'OID assign� au nouvel objet large ou InvalidOid (z�ro) en cas d'erreur.
Un exemple :
inv_oid = lo_creat(conn, INV_READ|INV_WRITE);
Pour importer un fichier du syst�me d'exploitation en tant qu'objet large, appelez
Oid lo_import(PGconn *conn, const char *filename);
filename sp�cifie le nom du fichier � importer comme objet large. Le code de retour est l'OID assign� au nouvel objet large ou InvalidOid (zero) en cas d'�chec. Notez que le fichier est lu par la biblioth�que d'interface du client, pas par le serveur. Donc il doit exister dans le syst�me de fichier du client et lisible par l'application du client.
Pour exporter un objet large en tant que fichier du syst�me d'exploitation, appelez
int lo_export(PGconn *conn, Oid lobjId, const char *filename);
L'argument lobjId sp�cifie l'OID de l'objet large � exporter et l'argument filename sp�cifie le nom du fichier. Notez que le fichier est �crit par la biblioth�que d'interface du client, pas par le serveur. Renvoie 1 en cas de succ�s, -1 en cas d'�chec.
Pour ouvrir un objet large existant pour lire ou �crire, appelez
int lo_open(PGconn *conn, Oid lobjId, int mode);
L'argument lobjId sp�cifie l'OID de l'objet large �
ouvrir. Les bits mode contr�lent si l'objet est
ouvert en lecture (INV_READ), �criture
(INV_WRITE) ou les deux. Un objet large ne peut pas �tre
ouvert avant d'avoir �t� cr��. lo_open
renvoie un
descripteur (positif) d'objet large pour une utilisation future avec
lo_read
, lo_write
,
lo_lseek
, lo_tell
et
lo_close
. Le descripteur est uniquement valide pour
la dur�e de la transaction en cours. En cas d'�chec, -1 est renvoy�.
La fonction
int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
�crit
len octets de buf
dans le descripteur fd de l'objet large. L'argument
fd doit avoir �t� renvoy� par un appel pr�c�dent �
lo_open
. Le nombre d'octets r�ellement �crits est
renvoy�. Dans le cas d'une erreur, une valeur n�gative est renvoy�e.
La fonction
int lo_read(PGconn *conn, int fd, char *buf, size_t len);
lit
len octets du descripteur de l'objet large
fd et les place dans buf.
L'argument fd doit avoir �t� renvoy� par un appel
pr�c�dent � lo_open
. Le nombre d'octets r�ellement lus
est renvoy�. Dans le cas d'une erreur, une valeur n�gative est renvoy�e.
Pour modifier l'emplacement courant de lecture ou �criture associ� au descripteur d'un objet large, appelez
int lo_lseek(PGconn *conn, int fd, int offset, int whence);
Cette fonction d�place le pointeur d'emplacement courant pour le descripteur de l'objet large identifi� par fd au nouvel emplacement sp�cifi� avec le d�calage (offset). Les valeurs valides pour whence sont SEEK_SET (rechercher depuis le d�but de l'objet), SEEK_CUR (rechercher depuis la position courante) et SEEK_END (rechercher depuis la fin de l'objet). Le code de retour est le nouvel emplacement du pointeur ou -1 en cas d'erreur.
Pour obtenir la position actuelle de lecture ou �criture d'un descripteur d'objet large, appelez
int lo_tell(PGconn *conn, int fd);
Un descripteur d'objet large peut �tre ferm� en appelant
int lo_close(PGconn *conn, int fd);
o� fd est un descripteur
d'objet large renvoy� par lo_open
. En cas de succ�s,
lo_close
renvoie z�ro. Renvoie 1 en cas de succ�s, -1
en cas d'�chec.
Tous les descripteurs d'objets larges restant ouverts � la fin d'une transaction seront automatiquement ferm�s.
Pour supprimer un objet large de la base de donn�es, appelez
int lo_unlink(PGconn *conn, Oid lobjId);
L'argument lobjId sp�cifie l'OID de l'objet large � supprimer. Dans le cas d'une erreur, le code de retour est n�gatif.
Pr�c�dent | Sommaire | Suivant |
Fonctionnalit�s d'impl�mentation | Niveau sup�rieur | Fonctions du c�t� serveur |