vsnprintf() fonksiyonu

Bildirim

Açıklama

Arg parametresi ile gösterilen değişken argüman listesinden aldığı değerleri format parametresi ile gösterilen karakter dizisi içinde düzenleyerek sonuçları boyutu bufsize parametresi ile tanımlanan ve buffer parametresi ile gösterilen karakter dizisine yazar.

En fazla bufsize-1 kadar karakter yazılır. Sonuçta ortaya çıkan karakter dizisi, bufsize sıfır olmadıkça boş bir karakterle ('\0') sonlandırılır. Eğer bufsize sıfır ise, hiçbir şey yazılmaz ve buffer NULL bir işaretçi olabilir, ancak dönüş değeri hesaplanarak geri döndürülür.

Format parametresi ile gösterilen karakter dizisi içinde yer alan karakterleri normal bir şekilde, % işareti ile başlayan format tanımlayıcılarını ise tanımlanan her bir format tanımlayıcı için, arg parametresi ile gösterilen değerler listesinden sıra ile değer okuyarak format karakter dizisini buffer ile gösterilen karakter dizisine yazar.

snprintf() fonksiyonunda format tanımlayıcılarına değer okutmak için format parametresinden sonra gelen ek parametreler kullanılırken vsnprintf() fonksiyonunda arg parametre listesinde yer alan değişken adresleri kullanılmaktadır.

Her durumda, arg parametre değerine vsnprintf() fonksiyonu kullanılmadan önce va_start() fonksiyonu tarafından bir ilk değer verilmiş olmalı ve fonksiyon kullanımından sonra ise va_end() fonksiyonu tarafından serbest bırakılmalıdır.

Kontrol dizisinin içinde hem normal karakterler hem de % işareti ile başlayan format tanımlayıcıları adı verilen ifadeler yer alabilir. vsprintf() fonksiyonu " " işaretleri arasında yer alan normal karakterleri sıra ile akışa yazar. Kontrol dizisi içinde yer alan her bir format tanımlayıcısı için arg parametresi ile gösterilen liste içinden sıra ile bir değer tanımlanır. Ancak, burada dikkat edilmesi gereken 2 önemli nokta vardır:

Fonksiyon çalışmaya başladığında, önce kontrol dizisi içinde yer alan ilk karaktere bakar. Eğer normal bir karakter ise hemen karakter dizisine yazar. Eğer bir format tanımlayıcısı ise, bu format tanımlayıcısına karşılık gelen arg parametresi ile gösterilen listedeki ilk argüman değerini karakter dizisine yazar. Kontrol dizisi içindeki bütün karakterleri sıra ile bu şekilde kontrol edip işlem yaptıktan sonra çalışması sona erer.

Format tanımlayıcıları kendilerine karşılık gelen argümanların buffer karakter dizisine nasıl yazılacağını belirler. vsnprintf() fonksiyonu format tanımlayıcıları ile karşılaştığında buffer karakter dizisine farklı bir veri yazacağını ve bu verinin vsnprintf() fonksiyonu çağrılırken karakter dizisinden sonra tanımlanmış olan arg liste değerlerinden sıra ile alınacağını anlar.

Vsnprintf_s() fonksiyonu aynı işlemleri yapar. Farklı olarak, çalışma zamanında aşağıdaki hatalar tespit edildiğinde, yüklenmiş olan kısıtlayıcı işlem fonksiyonu çağrılır:

Parametreler

buffer: Format parametresinde oluşturulan karakter dizisinin yazdırılacağı karakter dizisidir.

bufsize: Buffer parametresi için maksimum boyutu tanımlar.

format: Buffer parametresine yazdırılacak olan bir karakter dizisidir.

Bu karakter dizisi buffer karakter dizisine yazılacak olan metni içerir. Karakter dizisi içinde normal karakterler veya % karakteri ile başlayan ve format karakter dizisinden sonra gelen arg parametresi ile gösterilen listedeki değerlerle sıra ile doldurulacak olan format tanımlayıcıları yer alabilir.

Format tanımlayıcı genel yapısı :

%[göstergeler][genişlik][.hassasiyet][uzunluk]format tanımlayıcısı

Bir format tanımlayıcısı toplam 6 farklı ifadeden oluşmaktadır. En baştaki % işareti ile en sonda yer alan format tanımlayıcı harfi mutlaka kullanılmalıdır. [] işaretleri arasında yer alan diğer dört ifade isteğe bağlı olarak kullanılır.

uzunluk : İsteğe bağlı olarak tanımlanan bu değer okutulacak argümanın boyutunu gösterir. hh, h, l, ll, j, z, t, L değerlerinden biri kullanıldığında, karşılık gelen argümanın gösterdiği veri tipini değiştirir.

arg : va_start() ile ilk değer verilen değerler listesini tanımlayan bir değerdir.

Dönüş değeri

Vsnprintf() fonksiyonu buffer parametresine yazılan karakter sayısını int bir değer olarak geri döndürür. Hata durumunda negatif bir sayı geri döndürür. Eğer, sonuçta elde edilen karakter dizisi bufsz parametre değerinin getirdiği sınır nedeniyle kesilirse, fonksiyon format parametresine geçirilen yazılacak olan toplam karakter sayısını (sonlandırıcı boş karakter hariç) geri döndürür.

Vsnprintf_s() fonksiyonu buffer parametresine yazılan karakter sayısını int bir değer olarak geri döndürür (sonda yer alan boş karakter hariç ('\0')). Eğer bir çalışma zamanı kısıt ihlal hatası veya bir kodlama hatası oluşursa negatif bir sayı geri döndürür.

Örnek

#include <stdio.h>
#include <stdarg.h>

void ArgList(int write, char *buffer, const char * format, ...);

int main(void)
{
    char buffer[100];
    char cd;
    int id;
    float fd;
    char cdizi[20];

    /* Karakter dizisine yazma işlemi */
    ArgList(1, buffer, "%c %d %.2f %s", 'P', 92, 843.25, "Bilgisayar");

    /* Karakter dizisinden okuma işlemi */
    ArgList(0, buffer, "%c %d %f %s", &cd, &id, &fd, cdizi);
    printf("Karakter dizisinden okunan değerler: %c %d %.2f %s", cd, id, fd, cdizi);

    return 0;
}

void ArgList(int write, char *buffer, const char *format, ...)
{
  va_list args;
  va_start (args, format);
  if (write) vsnprintf (buffer, 100, format, args);
  else vsscanf (buffer, format, args);
  va_end (args);
}

Yukarıdaki örnekte, program aşağıdaki satırı ekrana yazar:

Karakter dizisinden okunan değerler: P 92 843.25 Bilgisayar

Program birer adet char, int, float ve karakter dizisi değeri oluşturur. Değerlere karşılık gelen format tanımlayıcılarını içeren bir karakter dizisi ile farklı değerleri kullanarak ArgList() fonksiyonunu karakter dizisine yazma amacıyla çağırır. Fonksiyon içinde va_start() ile oluşturulan argüman listesi ve format parametre değeri ile vsprintf() fonksiyonu çağrılarak karakter dizisine yazma işlemi yapılır. Daha sonra aynı işlemler vsscanf() fonksiyonu ile karakter dizisinden okuma amacıyla yapılır. Okunan değerler ekrana yazılır.